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About This Manual 


The contents of the manual are grouped into fifteen sections: 


Section 1, Introduction, highlights key concepts that are essential to the 
system programmer. 


Section 2, PL-6 for System Programming, includes an annotated example of the 
use of monitor services in PL-6 programs. 


Section 3, X Account Tools, discusses tools available to the system 
programmer. 


Section 4, Processor Conventions, describes guidelines which help to provide 
consistency in the user interface to the CP-6 system. 


Section 5, Source Code Documentation, describes conventions and tools for 
including extractable commentary in source code files. 


Section 6, Error Message Reporting, describes conventions and tools for error 
reporting and creation of error message files. 


Section 7, User Documentation/HELP, describes the $TEXT facility which 
simplifies and standardizes creation of user manuals and on-line CHELP) 
documentation. 


Section 8, Techniques: Central System, describes interfaces to central system 
software. 


Section 9, Techniques: Communications, describes interfaces to communication 
software. 


Section 10, Shared Run Units, describes sharing programs and the auto-sharing 
process. 


Section 11, Special Shared Processors, describes guidelines for writing 
Command Processors, Debuggers, and Alternate Shared Libraries. 


Section 12, Run-Time Libraries, describes how to build and associate run-time 
Libraries. 


Section 13, Library Functions, describes functions available from the 
:SHARED SYSTEM run-time Library. 


Section 14, Compilers and Language Utilities, describes conventions and tools 
to aid in writing Language processors. 


Section 15, Interlanguage Calling, describes calling and receiving sequences 
and related information. 


Appendix A, Job Information Table, describes the JIT information maintained 
for all active users of the system. 
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Notation Conventions 


The following table gives notation conventions used in this manual to describe 
commands, statements, directives, and other Language elements. 


Notation Conventions Table 


Notation Description 


Lower~case Letters 


Lower-case letters indicate that the element is a variable, to 
be replaced with the desired value. 


CAPITAL LETTERS 


Capital Letters indicate a literal, to be entered as shown. 


Special Characters 


Special characters are Literals, to be entered as shown. 


Numerals 


Numerals standing alone are Literals, to be entered as shown. 
Numerals embedded in or affixed to a string of capital letters 
are also literals, to be entered as shown, for example, PL6. 
Numerals embedded in or affixed to a string of lower case 


letters are part of the variable name to be replaced with a 
desired value, for example, fid1. 


Braces 


Elements stacked inside a pair of braces identify a required 
choice. The braces may be elongated to contain the possible 


choices, or may be represented by vertically-stacked printed 
braces. 


C{shift_count} means that either a value for 
{R11} shift _count or the word R1 must be 
entered. 


Alternatively, the vertical OR bar is used to separate the 
choices, thus: {shift _count|R1} 


The OR bar separates elements in a list from which one element 
may be, or must be, chosen. 
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Notation Conventions Table (Ccont.) 


Notation Description 


{Ri|shift_count} means that either the word R1 or the 
value of shift_count must be entered. 


Vertical Ellipsis 


The vertical ellipsis indicates that zero or more commands or 
instructions have been omitted. 


START CCP 
means that there are zero or more 
statements omitted between the 
CCP and END statements. 


Blanks 


Where blanks are shown in syntax formats, one or more blanks 
must be used except inside character Literal strings. 
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Section 1 


Introduction 


Interfaces and their use and manipulation are major strengths of the CP-6 
system. A guiding goal in implementing the CP-6 system was to build a system 
which did not need to be modified by the users or by Honeywell in order to 
adapt to special requirements. The system has been successful in this effort 
as judged by the exceptionally small number of site specific patches to the 
system and the lack of changes by addition and recompilation of system or 
processor modules. 


System programmers do change the way the system operates, however, largely 
through use and understanding of the interfaces documented in this guide. 
There are three major interfaces to the CP-6 system described in this guide: 


1. The user interface 
2. The compiler output or direct language interface 
3. The program calling interface 


File management, terminal and device I/0 interfaces which are equally 
important in using the system are described in the CP-6 Programmer Reference 
Manual (CE40) and the CP-6 Monitor Services Reference Manual (CE33). 


The CP-6 system presents a common, familiar, and consistent interface to the 
end-user. Standards used throughout the CP-6 system and in all its processors 
provide a consistent syntax; the same options mean the same thing throughout 
the system. The CP-6 parsing tools and standards are described here so that 
newly built processors can present the same consistent user interface. Many 
of the tools employed in the development of the CP-6 system are made available 
with the system in account X. A description of the most important and useful 
of the account X routines are described in Section 3. 


The standard object language provides a form for all compilers to produce 
loadable code and the debugging schema. Tools useful to compiler writers are 
also discussed. 


Standards for calling between programs allow subprograms in several Languages 
to be combined into a single program with each Language being used where it is 
strongest. 


CP-6 interfaces are also provided so that a site may create its own command 
Language, its own debugger, or its own database management system. Each of 
these is a type of shared program called a special shared processor. The 
rules for their creation and the privileged calls available to them are 
described in the sections that follow. User and system Libraries form another 
level of sharing in the CP-6 system. Rules governing these Libraries (which 
may be amended or recreated by the user) are given together with techniques 
which, if used, will allow change of the libraries without the need to change, 
reload or recompile programs which use them. 


CP-6 comgroups are a unique method for communicating between programs, and 
between programs and terminals or devices connected to the system. Comgroups 
form an internal message switching network within the CP-6 system. 
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Section 2 


PL-6 for System Programming 


PL-6 is the implementation language for the CP-6 system. The PL-6 language, 
which is intended for block-structured programming, provides simple syntax and 
simple data types. See the CP-6 PL-6 Reference Manual (CE44) for a complete 
definition of the Language. The first part of the Reference discusses 
concepts of the Language and its main features. 


PL-6 users must rely on monitor services, as documented in the CP-6 Monitor 
Services Reference Manual (CE33), for functions which the PL-6 compiler does 
not provide. The PL-6 CALL statement may be used to transfer control to any 
monitor service or Library service. In addition to the service subroutines, 
the CP-6 system provides macro definition for related structures which are 
INCLUDEd for use in the PL-6 program. 


To use a monitor service, the PL-6 program simply calls the needed service. 
Every monitor service has no more than one argument. The argument is the name 
of the Function Parameter Table, (FPT) which contains parameters specific to 
each monitor service. The program generates the FPT by using the macro 
structures supplied in the system macro library. (See the CP-6 Monitor 
Services Reference, CE33, for more information on the system macro Library). 


Figure 2-1 illustrates a program which uses several common monitor services 
and demonstrates the use of the system macros to set up the FPTs for the 
monitor services. The sample program is purposely brief. A somewhat longer 
Sample program is illustrated in the CP-6 Monitor Services Reference Manual. 
PL-6 program fragments are shown throughout this handbook. In addition, 
programs in account .:XSI are a source of examples, as discussed in Section'3. 
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/* 
Program to REKEY a file, starting with a key of 1.000 in 
increments of 1.000 

* / 

REKEY: PROC MAIN; 


Locally needed substitution 
strings (Z%EQUs) 
x / 
ZEQU TRUEH='1'B /*xTRUEH*/; 
ZEQU FALSE#='0'B /*FALSEA*/; 


INCLUDE all the system macros 
so we can set up the FPTs for 
the monitor services. 

* / 


XINCLUDE CP_6; 
XINCLUDE CP 6 SUBS; 


OCBs defined here 


MSSI DCB; 
MSOO DCB; 
MSDO DCB; 


EXTERNALS 


BSTCB$ PTR SYMREF; 


/* 
Local STATIC storage 


BUF1 CHAR(256) STATIC INIT(' '); 
BUFIARS UBIN WORD STATIC; 


MS$SI$ PTR STATIC; 
MSOO$ PTR STATIC; 


1 00 KEY STATIC, 
"2 * UBIN BYTE CALIGNED INIT(3), 
2 KEY _ UBIN(27) CALIGNED INIT(O); 


DCL MY ERROR BUF CHAR(255) STATIC CALIGNED; 
DCL FPARAM BUF(O:1025) SBIN STATIC ALIGNED; 


/* 
Invoke the macros that got INCLUDEd in CP_6 to set 
the information needed by the monitor services. 


%FPT_ERRMSG CFPTN=ERROR_ PRINT, 
BUF=MY ERROR BUF, 
DCB=M$SI, 
OUTDCB1=M$D0, 
CODE=NIL); 


Figure 2-1. Sample PL-6 Program (cont. next page) 
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%FPT_OPEN CFPTN=OPEN SI_IN, 
FPARAM=FPARAM BUF, 
DCB=M$SI); 


%FPT OPEN (FPTN=OPEN 00 OUT, 
DCB=M$00, 
FUN=CREATE, 
EXIST=NEWFILE, 
ASN=FILE, 
ACS=DIRECT, 
IFPARAM=FPARAM BUF, 
ORG=KEYED); ~ 


%FPT_READ CFPTN=READ BUF1, 
DCB=MSSI, 
BUF=BUF1, 
WAIT=YES); 


XFPT WRITE CFPTN=WRITE 00 BUF2, 
DCB=M$00, 
BUF=BUF1, 
ONEWKEY=YES, 
KEY=00_KEY, 
WAIT=YES); 


%FPT_CLOSE CFPTN=CLOSE SI _REL, 
DISP=RELEASE, 
DCB=M$SI1); 


%FPT CLOSE (FPTN=CLOSE 00 SAVE, 
DISP=SAVE, 
DCB=M$00); 


Invoke the MACROs to generate 
based structure for accessing 
data in the TCB, DCB and ALTRET 
frame. 
x / 
XFSDCB; 
*BSTCB; 


%BSALT; 


ZAEJECT; 


MSSI$ DCBADDR (DCBNUM(M$SI)); 
MSOOS DCBADDR(DCBNUM(M$OO0)); 


/* 
Set up the file name in the 
OPEN FPT and call the monitor 
service routines to open the 
necessary files. 
* / 
OPEN 00 OUT.NAME _ = VECTOR(MSSI$->FSDCB.NAME#); 


CALL MSOPEN COPEN SI_IN) ALTRET (MXXX); 


CALL MSOPEN (OPEN 00 OUT) ALTRET (MXXX); 


Figure 2-1. Sample PL-6 Program (cont. next page) 
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/* 
READ record, update the key, 
WRITE it out and so on.... 
until we hit the end of file. 
xf 


DO WHILE (X%TRUEA); 


BUF1T = ' '; 
CALL MSREAD (READ _BUF1) ALTRET (MUST _BE_END_OF FILE); 


BUFTARS = MS$SI$->FSDCB.ARSA; 
OO_KEY.KEY = 00 KEY.KEY_ + 1000; 
WRITE 00 BUF2.BUF_.BOUND = BUF1ARS; 
CALL MSWRITE (WRITE 00 BUF2) ALTRET (MXXX); 
END; /* 0O WHILE TRUEH */ 
/* 
An error occurred somewhere, 
get the error code and print 
the error message. 
*/ 
MAXXX: ; 
ERROR PRINT.CODE_ = VECTOR(BSTCBS$->BSTCB.ALTS->BSALT.ERR); 
CALL MSERRMSG CERROR_ PRINT) ALTRET CHMMM) > 
HMMM: ; /x Abort this job, something went wrong */ 
CALL MS$XXX; 


MUST BE END OF FILE:; /* So close the open files and exit. */ 


CALL MSCLOSE (CLOSE 00 SAVE) ALTRET (MXXX); 
CALL MSCLOSE (CLOSE SI_REL) ALTRET (MXXX); 
CALL MSEXIT; 


END REKEY; 


Figure 2-1. Sample PL-6 Program 
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Section 3 


X Account Tools 


X Account Policy 


The X Account provides a toolcrib for unsupported tools on the CP-6 system. 
Tools that are placed in this account may be of use to a small or large number 
of users. Any tool that is used by more than two individuals is a candidate 
for inclusion in the X Account. 


The X Account tools provide users with programming examples of techniques and 
standards for using the CP-6 system. There are no access restrictions to the 
account; most of the source code used to create it is delivered to customer 
sites. 


X Account Support Mechanisms 


The X Account contains tools that are not supported through the normal support 
mechanisms provided with the CP-6 system. However, in the case of deficiency 
or oversight, or if a new feature is needed, a Severity D STAR may be 
submitted to STARLOG with the subject Listed as Product X. There is no 
guarantee that the suggestion will be implemented in a timely manner, but the 
tool's originator may be able to provide help and advice through STARLOG 
responses, 


X Account Naming Conventions 


As released, the X Account tools are put in the .:XSI account which contains 
the source, HELP, JCL and rununits of all the tools. The job $BUILD X_ACCT 

copies all the essential elements into the X Account. The following naming 

conventions are used for the .:XSI account. 


e TOOL _SIcn Csource) 

e TOOL”HELP (HERMAN input) 

e TOOL CRU (Sample JCL) 

e TOOL _Ccn (Include, copy files) 


where c is a compiler indicator, and n is a digit. 
NOTE: If files in the :XSI account appear not to exist, consult 


the system manager to determine if the account was created with 
appropriate access permissions granted. 
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Contents of the X Account 


The X Account contains approximately 175 tools; the most frequently used tools 
are documented in this section. The X Account is constantly being changed and 
updated; therefore, tools may disappear or appear in the account at the 
different releases. The tools may be categorized as follows: 


Programmer aids 

System Programmer aids 
Integration aids 
Installation Management aids 
Documentation aids 

Support aids 


Microprocessor Support aids 
Miscellaneous tools 


Programmer Aids 


Programmer aids are tools that are of general use to the application 
programmer in all languages. These tools cover a wide spectrum of 


applications -- from tools that inform the user about the status of the system 
to tools that List HELP files. 


Table 3-1. X Account Programmer Aids 
Tool Name Description 


Records and reports the status of batched jobs. 


BANNER 


Prints user specified text in block Letters on a Line printer. 


CALENDAR 


Builds, displays and stores a user's personal calendar. 


Displays information about the system such as the number of 
users, the ETMF and 90% response time. 


DILDEV 


Displays a user's current Logical DEVices and how much output 
is queued up for each of them. 


Positions output to a new page. 
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Table 3-1. xX Account Programmer Aids (cont.) 


Tool Name Description 


EMU 
The Error Message Uncoder prints the CP-6 error message text 
associated with a specified error code. 
FIND 
Searches account(s) for a given filename or prefix. 
GOPHER 
Displays the filename and Lines within it that contain the user 
specified string. 
LISTHELP 
Lists one or more HELP files on the specified destination. 
OVERLAP 
Reads an FPL source program and then can be directed to check 
for overlapping fields and/or print one or more forms described 
in the program. 
OX 
Provides a cross reference of a FORTRAN 77 program and/or 
subroutines. 
PMDISP 
Displays Performance data gathered via PMON.X or PM.X. 
PMON 
Software Performance MONitor used with PMDISP.X and PM.X. 
RQ 
Displays information about the running or input/output queues. 
SETUP 
Is a universal setup program which eliminates the need to go 
through IBEX. 
SKUNK 


Locks your terminal and keeps someone from using it while 
you're away. 
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Table 3-1. X Account Programmer Aids (cont.) 


Tool Name Description 


Displays severity Level of rununits and object units. 


System Programmer Aids 


System programmer aids are tools that are of use to programmers working in an 
environment that maintains a source base. These development tools can be used 
by a wide range of users on the CP-6 system. Many of these tools such as CMPR 
or LIN are used to maintain and update the source base. 


Table 3-2. xX Account System Programmer Aids 


Tool Name Description 


Allows a user to raise or lower the batch queue priority of 
subsequently batched jobs. 


BOOKWORM 


A program designed to aid in the electronic preparation of 
table of contents and indexes from TEXT files. 


Compares two files and generates update files. 


Converts PL-6 DCL statements to pictures, for use in debugging 
PL-6 structures, design specs, technical manuals, etc. 


EDGEMARK 


Prints specified text in block letters on the edge of a 
print-out. 


Puts extractable commentary into code. 


FORMAT 


Formats (i.e., pretty prints) PL-6 source files, merges updates 
and inserts copyright notices. 
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Table 3-2. xX Account System Programmer Aids (cont.) 


Tool Name Description 


LISTER 


Takes a file of plus records and gives them proper edit keys. 


Validates and rekeys plus-card files. 


Merges Lines from a base file and puts them into plus-card 
format. 


Copies selected portions of unit-record Listing files (produced 
by PL-6, PL1, PARTRGE, BMAP, or GMAP6) to the Line printer. 


Allows a user on a multiprocessor system made up of different 
CPU types to specify the CPU on which he wants to run. 


PARSE/PARSEOU 


PARTRGE 


UNGMAP 


CE62-00 


Tools used with the parser and PARTRGE to tell the user what 
the output nodes Look like after a parse. 


Creates parse node object units. 


Dumps debug schema from an object unit file, run unit file 
an overlayed run unit file. 


Takes an object unit and produces an assembly listing from 


Displays information about the current running system. 
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Integration Aids 


CP-6 integration tools are tools used in integrating and distributing the CP-6 
system. 


Table 3-3. XxX Account Integration Aids 


Tool Name Description 


Converts PL-6 DCL statements to pictures, for use in debugging 
PL-6 programs, design specs, technical manuals, etc. 


Converts files containing PL6 DCL statements and pre-processor 
directives into files with corresponding SYMREF and/or BASED 
DCLs. 


EDGEMARK 


Prints specified text in block Letters on the edge of a 
print-out. 


EXTRACT 


Extracts error messages and commentary from source code. 


FICHER 


Takes Listing and source files and creates a set of tapes for 
printing on microfiche. 


HERMAN 


Reads a text file containing HELP and HERMAN commands and 
creates a HELP database. 


INSREC 


Inserts records from a base file into another file based on a 
control file. 


LINKMOD 


Alters LINK, PCL and/or LEMUR JCL. 


Reports on multiple occurrences of update files. 
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Table 3-3. xX Account Integration Aids (cont.) 


Tool Name Description 


MODMOVE 


Controls the manipulation of update files in controlled 
accounts. 


Removes unwanted schema from OBJECT and RUN units. 


Places software technical identifiers into released software. 


Installation Management Aids 


Installation management aids are tools that are useful to CP-6 system 
managers. These tools help manage the machine efficiently by giving 
information about the state of the machines such as what users have certain 
privileges or which remote terminals are connected. 


Table 3-4. xX Account Installation Management Aids 


Tool Name Description : 


AUTO 
Allows a user to raise or lower the batch queue priority of 
subsequently batched jobs. 
COBWEB 
A tool that installs and deletes shared processors. 
EXPIRED 
Prints the names of files which have expired as of the current 
date. 
FWEDITOR 
Builds and edits a customized firmware file from an IFAD tape. 
GRAMPS 


Watches for disk packs that are running out of space. 
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Table 3-4. xX Account Installation Management Aids (cont.) 


Tool Name Description 


MPC DUMP 


Provides a hexadecimal dump of an MPC's main memory separated 
by its memory content headings. 


PRIVCHECK 


Checks running users privileges against the privileges for 
which they were authorized. 


PRIVDISP 


Displays the logon id of users who have the requested 
privileges. 


Displays certain 
system. 


information about current users on a CP-6 


Aids in analyzing performance by displaying certain fields from 
the specified users’ JIT. 


Tells which remote terminals are connected or have output 
queued. 


Converts user authorization files into newer versions. 
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Documentation Aids 


These tools are, to the Largest extent, used in documentation preparation 
along with CP-6 TEXT. They include a proofreading dictionary as well as a 
tool that creates indices. 


Table 3-5. X Account Documentation Aids 


Tool Name Description 


BOOKWORM 
A program designed to aid in the electronic preparation of 
table of contents and indices from TEXT files. 
EDICT 
Puts extractable commentary into code. 
EXTRACT 
Extracts error messages and commentary from source code. 
FIXTEXT 
Strips leading and trailing blank Lines from TEXT-produced 
output files, thus making them more suitable for use with other 
processors. 
FORMAT 
Formats (i.e., pretty prints) PL-6 source files, merges updates 
and inserts copyright notices. 
HERMAN 
Reads a text file containing HELP and HERMAN commands and 
creates a HELP database. 
LISTHELP 
Lists one or more HELP files on the specified destination. 
NOBS 
A program that reads a TEXT input file and changes 
backspaced/underscored passages into a format compatible with 
CP-6 FEP input functions. 
PROOF 


Is a document proofreader with an accompanying dictionary. 
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Table 3-5. X Account Documentation Aids (cont.) 


Tool Name Description 


A program to TUNe An edit-keyed text input file so that it can 


be edited on an 80 column CRT screen. 


UNPRINT 


Reads text files and reports on any unprintable characters 
found. 


Development Management Aids 


These are tools that support the system design as well as reporting system 
progress. 


Table 3-6. X Account Development Management Aids 


Tool Name Description 


Copy Review File. CRF is used to review files to which 
additional information may be appended at regular intervals.” 


LNCOUNT 


Counts the number of comment and source lines in files in 


controlled accounts and reports this information to a Unit 
Record file or Terminal. 
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Support Aids 


These tools provide a mechanism for both programmers and support personnel to 
support the software and customers. 


Table 3-7. X Account Support Aids 


Tool Name Description 


BEAM/MAEB 


Transports files between CP-6 systems. 


CGDUMP 


Reads a closed comgroup file and any monitor dump file, and 
creates a dump file that can be used with ANLZ to Look at the 
comgroup tables. 


ELBBIRD 


Converts files created by the DRIBBLE command from its original 
form to a form more easily used in documentation. 


MOVE/SCOTTY 


Transports files to and from other CP-6 systems. 


Formats patches. Inserts pertinent information such as the 
date, STAR number, etc. 


RUMSPLIT 


Takes a file containing RUM directives and splits it into 
smaller files, each containing a single product's RUMs. 


TATTLE 


Informs a Honeywell programmer when a test case has arrived 
the ZZZTEST account. 


WOODPECKER 


Allows a user without the DISPJOB privilege to display all 
output destined for his Workstation of Origin. 
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Microprocessor Support Aids 
These tools provide the user with several types of assemblers. 


Table 3-8. xX Account Microprocessor Support Aids 
Tool Name Description 


A program that provides the required handshaking for down-line 
loading of ASMZ80.X and ASM6502.X run units into a 
micro-processor. 


ASM6502 


6502 Cross-Assembler for CP-6. 


MSA6800 


reverse assembler for 6800-based machine code. 


MSA8085 


reverse assembler for 8085-based machine code. 


MSAZ80 


reverse assembler for Z80-based machine code. 


Miscellaneous Tools 


These tools provide programs in the common tool crib which are of common 
interest and relatively high usage. 
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Table 3-9, X Account Miscellaneous Tools 


Tool Name Description 


COPYPGM 


Copies records, portions of records, or constant information 
from one file to another. Records may be copied based on 


Boolean criteria supplied by the user. 


Is a cross between EDIT and PCL with some extensions. It works 
with most file organizations and has no built in restrictions 
on maximum record Lengths. 


X Account Tool Invocation 


The tool invocation command for tools in the X Account is: 


'toolname.X Coptions) 


For those tools that, because of their nature, reside in the :SYS account 
Ci.e., SPY) the tool invocation command is: 


!toolname Coptions] 


HELP for X Account Tools 


All of the tools that are in the X Account have HELP files. These files can 
be exercised by the following command: 


"HELP (Ctoolname.X) 
for tools in the X Account. 


'HELP (Ctoolname) 


for the tools that have been moved to the :SYS account. 
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X Account Programming Examples 


The X account, besides being a tool crib for commonly used tools can provide 
PL-6 programming examples. Figure 3-1 shows a user examining the HELP file 
for a tool called TUNA.X. 


‘HELP (TUNA.X) 
TUNA is a tool to TUNE A edit-keyed text input file so that it will be 


RR-EDITable on an 80-column CRT screen. 
{9 


Full command Line syntax: 


ITUNA.X text_file CCON|INTO|OVER} scratch file] CCoptions(£[)]] 


where: 
text _file is a TEXT input file containing TEXT directives 


scratch file is an optional file name to be used for scratch area. The 


default scratch file is *G. The scratch file is automatically deleted 
upon TUNA exit. 
19 


Options are: 


NWA/RN don't print warning messages about unknown macros 
NWR/AP don't attempt to wrap text from one Line to the next 
NUS/BS don't attempt to change the order of char/backspace/underscore 


to underscore/backspace/characer 


MA/XCOMPRESS try to compress all excess spaces out of a Line except 
those around the first word on an input record 


LEN/GTH=Line_ length sets the size of the records that TUNA will attempt 
to produce. The default is 69, which is right for editing on an 
80-column CRT. Allowable range is 50 through 132. 


MAXCOMPRESS and NWRAP are mutually exclusive options. 


Figure 3-1. Browsing through X Account HELP 


The source code for the X account is stored in the :XSI account. The two 
source code files for TUNA can be used as a model for parsing commands input 
that contains a list of options. Figure 3-2 examines the TUNA program 

(TUNA _SI6.:XSI) which calls the X$PARSE Library service and contains the 
required DCL statements needed to define structures to be passed to XS$PARSE. 
Figure 3-3 demonstrates how the parse nodes for TUNA Cin TUNA SIN.:XSI) 
correspond to CASE statements in TUNA_SI6. In both figures underscoring is 
used to highlight what the user typed. 
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'L TUNA?.:XSI 
TUNA_SI6 TUNA_SIN 
as 2 files listed 
'E TUNA SI6.:XSI 
EDIT BOS HERE 
* File TUNA SI6.:XSI is open input - cannot update 
*FTO- 9999, /0PTIONS/OR/tion/ 
58 CONSTANT definitions here 
118 (' *x*x**k NUSBS option automatically invoked.'); 
135 OPTIONS flags 
315 BASED definitions 
350 DO; /* MUST BE OPTIONS ON CMD LINE x*/ 
400 END; /* DO IF OPTIONS ON CMD LINE */ 
407 END; /* DO IF CONFLICTING OPTIONS */ 
1087 DCL STD_ERROR CHAR(O) STATIC INIT (* **** Bad option(s)'); 
1088 DCL ADV_ERROR CHAR(O) STATIC INIT (' x*e** Conflicting options'); 
* EOF hit after 1127 
*TY350 
350 00; /x* MUST BE OPTIONS ON CMD LINE */ 


*TP9 


341 KKKKKKKKKKEK KKK KKK KKK KK KKK KK KKK KKK KKK K KKK KKKKKKKKKR KKK KKK x/ 
342 
343 MSSI$ DCBADDR(DCBNUM(MS$SI1)); 
344 MSOUS DCBADDR(DCBNUMC(M$OU)); 
345 
346 TUNA PCB.ROOTS = ADDR(TUNA NODES); 
347 
348 IF BSJITS—>BSJIT.CCARS > BSJITS->BSJIT.CCDISP 
349 THEN 
*TY348 
348 IF BSJITS->OBSJIT.CCARS > BSJITS->BSJIT.CCDISP 
x"WHOA...THIS IS HOW TO KNOW THERE'RE OPTIONS ON THE COMMAND LINE!" 
*TN8 
349 THEN 
350 DO; /* MUST BE OPTIONS ON CMD LINE */ 
351 
352 TUNA PCB.TEXTS = PINCRCCADDR(BSJIT.CCBUF) ,BSJIT. CCDISP+1); 
353 TUNA _PCB.NCHARS = BSJIT.CCARS - BSJIT. CCDISP - 1; 
354 
355 CALL X$PARSE (TUNA PCB) ALTRET (XPERR); 
356 a 
*TY352 
352 TUNA _PCB.TEXTS = PINCRCCADDR(BSJIT.CCBUF) ,BSJIT.CCDISP+1); 
*"THIS IS HOW TO TELL THE PARSER WHERE TO FIND THE TEXT TO PARSE" 
aTY353 ~~ _ Copy te tN Siege pe ety eeu Re Se 
353 TUNA_PCB.NCHARS = BSJIT.CCARS - BSJIT.CCDISP - 1; 
*"AND THIS IS TO TELL THE PARSER HOW MANY CHARACTERS TO PARSE" 


Figure 3-2. Program Sample from :XSI Account - Part 1 
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*"WHERE'RE THE PARSE NODES?" 
*E TUNA SIN.:XSI 


x File TUNA SIN.~:XSI is open input - cannot update 
*TY 


1 /*M* TUNA SIN - Nodes for "TUNA" program. */ 

2 [KV KKKKKKKKKKKKKKKKKKKK KKK KKK KKKKKKKKKKKKKKKKKK KKK KK KKK KKK KKK 
3 xT * * 
4 *T* COPYRIGHT, (C) HONEYWELL INFORMATION SYSTEMS INC., 1982 * 
5 Tx * 
6 KT KKK KKK KKIKKRKKKIKAKKKKKKKKKKKKKKaKKKK KKK KKK KKK KK KK KK KKK KK / 
7 /*X* DMC,DFC */ 

8 

9 TUNA_NODES(D,OUT)=(< ',',TUNA_CMDS > C')'J] .END|NULL_CMD C')'J .END) 
10 
11 TUNA_CMDS = C.B] ( MAXCOMPRESS | ; 
12 NWRAP | ; 


NWARN ) 
MAXCOMPRESS(1)='"MA/XCOMPRESS' 
NWRAP(2)="NWR/AP! 
NUSBS(3)="NUS/BS' 


NWARN(4)="NWA/RN' 


NULL_CMD(5) ( .B | C.B] ) 


SIZE_OPT(6) 
* EOF hit after 27 


*"THERE'RE THE PARSE NODES! LOOKS A LOT LIKE THE HELP FILE!" 
* 


*" GO BACK TO SEE WHAT THE PARSER DOES" 
*E TUNA SI6.:XSI 


* File TUNA SI16.:XSI is open input - cannot update 
*TY353 


"LEN/GTH' '=" .DEC3 


353 TUNA _PCB.NCHARS = BSJIT.CCARS - BSJIT.CCDISP - 1; 
*TN23 
354 
355 CALL X$PARSE (TUNA PCB) ALTRET (XPERR); 
356 
357 DO WHILE (FALSE#); 
358 XPERR: ; 
359 CALL PARSE ERROR(1); 
360 GOTO GET GONE; 
361 END; /* DO WHILE PARSE ERROR */ 
362 
363 DO I = 0 TO TUNA PCB.OUTS -> TUNASOUTBLK.NSUBLKS ~ 1; 
364 
365 DO CASE (TUNA PCB.OUT$ -> TUNASOUTBLK.SUBLKS$(I) -> 
366 TUNASOUTBLK. CODE); 
367 
368 CASE (1); 
369 MAXCOMPRESS = TRUEM; 
370 
371 CASE (2); 
372 NWRAP_ = TRUE#; 
373 
374 CASE (3); 
375 NUSBS_ = TRUE#; 
376 
*TY368 
368 CASE (1); 


*"HMMM...THIS CASE(1) MATCHES THE NUMBER ON THE NODE IN THE PARSE NODE FILE!" 
*TY377-391 


Figure 3-3. Program Sample from :XSI Account - Part 2 (cont. next page) 
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CASE (4); 
NWARN = TRUE#; 


CASE (5); 


CASE (6); 
CALL CHARBIN (MAX _PER_LINE, 
TUNA _PCB.OUT$ -> TUNASOUTBLK.SUBLKS$(I) -> 
TUNASOUTBLK.SUBLK$(0) -> TUNASSYM.TEXT); 


IF MAX PER LINE > LEN _LARGE# 
OR 
MAX PER LINE < LEN SMALL# 
THEN 
DO; 
*TY383-385 
383 CALL CHARBIN (MAX PER LINE, 
384 TUNA_PCB.OUTS -> TUNASOUTBLK.SUBLK$(I) -> 
385 TUNASOUTBLK.SUBLKS(0) -> TUNASSYM.TEXT); 
*"AND IT LOOKS LIKE I HAVE TO MANUALLY CONVERT PARSED DECIMAL NUMBERS THAT" 
*" THE PARSER RETURNS INTO INTERNAL FORMAT TO...." 
*xT™N10 


IF MAX PER LINE > LEN LARGE# 
OR 
MAX _PER_LINE < LEN SMALL# 
THEN 
DO; 
CALL PARSE _ERROR(3); 
GOTO GET GONE; 
END; = /* DO IF NUMBER TOO BIG 


*"DO INTERNAL COMPARISONS WITH THEM!" 
* END 


Figure 3-3. Program Sample from :XSI Account - Part 2 
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Section 4 


Processor Conventions 


Conventions followed in writing Honeywell-supplied processors are discussed in 
this subsection. See Section 14 for conventions specifically applying to 
Language processors. 


General Case of Run Unit Invocation 


A run unit is invoked via the IBEX command 


'rununit Cruninformation] 


where 
rununit is the disk fid specifying the run unit. Standard disk fid rules 
apply. 
runinformation is additional text to be made available to the rununit in 


the user's JIT (BSJIT.CCBUF). The Length of the text in CCBUF is set in 
BSJIT.CCARS. If the command includes options, BSJIT.CCDISP contains the index 
of the left parenthesis preceding the options. If there are no options, 
CCDISP is set to the same value as CCARS. If the command is continued, 
BSJIT.CCBUF contains only the first Line of the command; the complete command 
(with any leading exclamation mark replaced by a blank) is written record by 
record to a star file, *CONTINUATION COMMANDS; the flag 
BSJIT.PRFLAGS.CONTINUED is set to indicate continuation. The file contains 
the semicolons entered to show continuation, as well as any comments. (CAt job 
step, the file is deleted and the flag indicating continuation is reset.) 


If the command is in the standard format (described in Section 14), the DCBs 
are set. If the run unit expects non-standard syntax, then it should be 
Linked without the SIDCB, UIDCB, OUDCB, and LODCB Link options. 


The run unit is then called. If the run unit was Linked with the STDINVOC 
option and the command is not in standard format, the run unit is aborted. 
Otherwise, it begins execution. 


IBEX does not force the program invocation to be of the standard form; such 
enforcement would be needlessly restrictive. Rather, a flag 
BSJIT.PRFLAGS.NSSYNTAX is set (='1'B) if the program invocation is 
non-standard. The invocation Line is made available to the program. The 
program may examine this flag and accept or reject the invocation, as desired. 
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Command Language Conventions 


The following command language syntax rules and guidelines are considered 
standard. These rules are observed by the command Language of IBEX, and by 
the command languages of the general use processors supplied for the CP-6 
system by Honeywell, for example, EDIT and PCL. 


1. Commands in the CP-6 common command language are not column dependent. 
Very few CP-6 commands are positional in the sense of having the 
significance of a parameter or operand denoted by its position in the 
command, except that some use is made of commands with a structure Like 


simple conversational English, for example: "COPY sourcefile TO 
destfile." 


2. Keywords can be typed in uppercase or lowercase or a combination of both. 
In CP-6 manuals, keywords are shown in uppercase. 


3. Multiple parameters are often organized as Lists, e.g., an optionlist is a 
parenthesis-~delimited List of options, separated by commas. 


4. Single parameters are connected to keywords in at least one of three ways: 


KEYWORD=parameter 
KEYWORD (parameter) 
KEYWORD=(Cparameter) 


5. A list of more than one parameter is connected to a keyword in one of two 
ways. 


KEYWORD(Cparameter, parameter) 
KEYWORD=(Cparameter,parameter) 


6. Comments within command streams are denoted by being enclosed in double 
quotation marks ("). 


7. Strings that contain delimiters must be enclosed by apostrophes ('); if an 


apostrophe is part of a string, it is denoted by adjacent apostrophes 
Ct ). 


8. The semicolon is a continuation indicator for multiple Line commands or 
the command separator for multiple commands on a single line. The 
semicolon cannot be used for continuation inside a keyword or text string. 
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Automatic File Extension 


Under certain circumstances, automatic file extension occurs. File extension 
means the process of adding data to the end of a non-keyed file, or of merging 
data into a keyed file. Automatic file extension applies to the situation 
that an initial step (rununit) of a job or session has created a given file, 
and subsequent job steps also perform writes to that file. When automatic 
file extension applies, the writes to a given file from a subsequent job step 
are written at the end of the writes to that file from the previous step (Cor 
merged with them if it is a keyed file); it is automatic in the sense that 
there is no need for file management commands intervening between the steps to 
position the file cursor. 


Performance of automatic file extension, at a given subsequent job step, of a 
particular file (fid) through its associated DCB, takes place under the 
following rules and conditions. 


1. The writes to the file take place through an eligible DCB. 


Eligible DCBs are: 


MSLO MSSI MSOU 
MSLL MSSO MSEI 
M$DO MSUI MSEO 
MSPO MSME 


2. After the first rununit is invoked, automatic file extension of a given 
fid through a given associated eligible DCB will take place unless or 
until: 

e A SET command is issued for the DCB, specifying a fid. 
® A RESET is done for this DCB, or a RESET ALL is done. 


3. For writes through M$LO, automatic file extension is cancelled if a LIST 
command that specifies a fid is issued. 


4. For writes through M$D0, automatic file extension is cancelled if a 
COMMENT command that specifies a fid is issued. 


Explicit file extension may be used if the "EXIST=oldfile" option is used on 
the SET command, or if the "INTO" preposition on the rununit call is used. 
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File Type Codes 


There is a convention concerning identification of the compiler or processor 
that created the object unit (or any other file) and the type of data 
incorporated in the file. The 2-character file type (ft) identifier codes 
shown in the Table 4-1 should be inserted in the FPT_OPEN.V.TYPE# field when 
the program is creating a file. The type code is provided for convenience and 
is not required for correct functioning of most system-supplied processors. 


Table 4-1. File Type Codes 


Codes Meaning 


First Character 


Data 

Database 

Object unit 

Run unit 

Source 

Update 

Work space 

IDS schema or ARES model 
IDS subschema 

System file not modified by the user 
nk = undefined 


rene Zkecunwmorse 


= 


on wu Uw tm NW i wt ou 


Second Character 


For Processor: 
APL 
ARES 
BASIC 
COBOL 
TRADER 
EDIT 
FORTRAN 
FPL 
GMAP6 
Ids 
IMP 
reserved 
Performance Monitor or PARTRGE 
IDP 
ata: 
ASCII 
APL data block attributes 
ASCII and single precision 
APL component file 
Double precision 
Single precision 
nk = undefined or unformatted 


D 
a 


A 
a 
B 
C 
D 
E 
F 
f 
G 
I 
J 
K 
P 
Qa 
r 
A 
a 
B 
c 
D 
Ss 
b 


t 
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Processor Termination Conventions 


Processors which operate by reading and acting on commands input by the user 
(as opposed to compilers) should accept the 'END' command as sufficient cause 
to terminate and return control to IBEX (by issuing the MSEXIT monitor call). 


Sample Interactive Processor 


Several library services are available to provide a consistent user interface 
to interactive processors. To provide a simple, readily comprehensible 
example of these services, Figure 4-1 illustrates a sample processor that 
actually performs no useful work. Instead it highlights the mechanics of 
defining a command language, sample processing command input, providing 
assistance with command syntax, reporting error messages, and reporting HELP 
messages. 


The sample processor, CORNER, consists of two modules of procedure. The main 
module (DEFSCORNER) solicits and parses commands, and reports syntax error 
messages and HELP messages. The internal procedure (DEG$BEAST) receives 
control for the CLEAN command, but for the sake of simplicity its only 
function is to report an error message. In addition, the sample processor 
contains a module of parse nodes (Figure 4-2) and a module of EQUs (Figure 
4-3) which together define the command syntax for CORNER. 


To demonstrate the user interface to the sample processor, Figure 4-4 shows an 
interactive session. Figure 4-5 shows the compilation, Linking, and other 
steps necessary to run the sample program. The following subsections discuss 
various aspects of the sample processor. 
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/*M* DEFSCORNER ~ Main module for the CORNER processor, 

CORNER: PROC MAIN; 

[xx/ 

LT HK KK IKK IKI ITI IIIT KK KKK KK KK KK KOTO IKK KK KKK ke ke te ke te te ke 
aT * * 
*T* COPYRIGHT, (C) HONEYWELL INFORMATION SYSTEMS INC., 1983 * 
aT* * 
FT RRO II III IOI IOI III TOI OI OI IO Ik toe / 

/xx/ 

ZINCLUDE CP 6; 

INCLUDE DEPS$FUZZY E; /* PARSE NODE EQUS 

ZINCLUDE XU MACRO Cc; /* XUR MACROS 

ZINCLUDE XUH _MACRO. C; /*x XUH MACROS 

ZINCLUDE XUR _ENTRY; /* XUR ENTRY DCLS 

ZINCLUDE XU_PERR_C; /* XUR ERROR EQUS 

/xx/ 

%VLP_NAME CFPTN = ERRF FID, 

NAME = ": ERRCORNER.! 
STCLASS = CONSTANT); 

DCL PROMPT CHAR(Q) CONSTANT INT reeCoRners ") 3 

4XUR _INIT (NAME=FPT _INIT, 
STCLASS= TONSTANT); 

[xx/ 

%XUH_ PARAM CNAME = XUH _PARAM, 
STCLASS = STATIC); 

DCL EXITING BIT(1) STATIC; 

%VLP_ERRCODE CFPTN = ERR _CODE, 

STCLASS = STATIC); 

DCL OUTS REDEF ERR _CODE PTR; 

[xx/ 

ZPARSESOUT (NAME=OUTSBLK, 

STCLASS=BASED); 

ZPARSESSYM CNAME = OUTSSYM, 

STCLASS = BASED); 

/xx/ 

DCL MS$DO DCB; 

DCL DEGSBEAST ENTRY(1) ALTRET; 

DCL FUZZY NODES BIT(1) SYMREF; 

[xx/ 

ZEQU FALSE# = '0O'B; 

ZEQU TRUEH = '1'B; 

[xx / 

EXITING = %FALSE#; 
CALL XURSINITCFPT INIT); 
CALL XURSSETERRMSGCERRF _FIO0); 


DO WHILE (NOT EXITING); 
CALL XURSGETCMDCFUZZY NODES,OUT$S,VECTOR(PROMPT)) ALTRET(PARSE _ERROR); 
DO CASE (OUTS -> OUTSBLK. CODE); 7 ON COMMAND TYPE */- 
CASE (XDEPS$HELP CMD4); 
XUH_PARAM.HELP$ = OUT$ -> OUTS$BLK.SUBLK$(0) -> OUTSSYM.TEXTC$; 
CALL XURSHELP (XUH _PARAM); 
CASE (%DEPSQUES CMD#); 
CALL XURSMOREMSG (XUH _PARAM) ; 
CASE (XDEP$QQ CMD#); 
CALL XURSALLMSG (XUH _PARAM) ; 
CASE (ADEPSCLEAN | CMDA) > 
enEL DEGSBEAST | (OUTS) ALTRETCITS OK); /* HAVE BEAST CLEAN UP */ 


CASE (%DEPSQUIT CMDA); 
EXITING = %TRUES; 
END; /* END CASE ON COMMAND TYPE */ 
DO WHILE (XFALSE#); 
PARSE ERROR: ; 


CALL XURSECHOIF (DCBNUM(M$D0)); 


Figure 4-1. Command, Error, HELP Processing Source (cont. next page) 
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IF ERR _CODE.ERR# = ZESSYNERR 
THEN 

CALL XURSERRPTR (€,DCBNUMCM$DO)); 
CALL XURSERRMSG CERR CODE); 


END; 
END; /* END WHILE NOT EXITING x / 
BAILOUT: ; 
CALL XURSCLOSE DCBS; /* CLOSE ALL DCBS WITH SAVE */ 
RETURN; 
END CORNER; 
/*Mx DEGSBEAST - BEAST module for the CORNER processor. */ 
DEGSBEAST: PROC (NODES) ALTRET; 
[xx / 
[KT RR KRKKKEKKKKKKKKKK KKK KKK KK Ka KR KKK aa KR Ra KR KR a RR KR aa KR KR RR KR aR RR KK 
*xT* * 
*T* COPYRIGHT, (C) HONEYWELL INFORMATION SYSTEMS INC., 1983 * 
xT * * 


KT KI KK KK KKK IKK IK II KIKI KKK KKK K KKK KKK KKK KKK KK KK KK IK / 
[xx/ 
ZINCLUDE CP 6; 


%ZINCLUDE DE PERR C; /* ERROR CODE EQUS */ 
“INCLUDE XUR_ENTRY; /* XUR ENTRY DCLS */ 
/*x*/ 

DCL NODES PTR; 

[xx / 


DCL FUZZINESS SBIN WORD STATIC INIT(99); 
AVLP_ERRCODE (FPTN = ERROR CODE, 
FCG = "DE", 
MID = "Gan, 
STCLASS = STATIC); 
[a / 
DCL MSOU DCB; 
%EQU MAXFUZZH = 18; 
/*xx/ 


IF FUZZINESS > ZMAXFUZZ# 
THEN 
DO; 
ERROR CODE.ERR# = ZDEGS$TOO FUZZY; 
ERROR CODE.SEV = 2; 
CALL XURSERRMSG CERROR CODE,DCBNUM(M$OU)); 
/*xEx ERROR: DEG-DEG$TO0O FUZZY#-2 
MESSAGE: File %%FN %too fuzzy. 
MESSAGE1: File “%%FN %is too fuzzy to use as a corner. 
DESCRIPTION: The file intended for use as a corner is unsuitable 
because it is too fuzzy for regular cleaning. This 
may be the result of prior contact with a beast. 
Until this code becomes more sophisticated, the 
work-around is to have the file dry-cleaned by a 
professional. 


* / 
ALTRETURN; 
END; 
. /x* Beasts too lazy to do any */ 
: /* cleaning; we'll do nothing */ 
RETURN; 
/xx/ 
END DEGSBEAST; 
/*M*x DE PERR_C - This module contains error %EQUs for CORNER */ 
/«x/ 
EME SECESELCLOS SSE SSSSSSSSSSSSSSSSOSCSOSLCISCLSOCSCSCLSCSCCCLSCISCLCCC CTL TF 
aT * 
*T* COPYRIGHT, (€C) HONEYWELL INFORMATION SYSTEMS INC., 1983 * 
aT* * 


KR] RRR KEKEKRKEKKEKKKKKKEKKEKEKEKEKKEKKKKKKKK KKK KK KKK KKKKKR KKK KKK KKKKEKK / 


ix / 


Figure 4-1. Command, Error, HELP Processing Source (cont. next page) 
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/x The following errors are generated in DEG$CORNER. */ 

/xx/ 

ZEQU DEGSTOO FUZZY#= 100/* DEGS$TOO FUZZY# x/; 

“ZEQU DEGSCORNER_ FULL#= 101/* DEGSCORNER FULL#A */; 

%ZEQU DEGSCORNER_INACCESSABLE#= 102/* DEGSCORNER_INACCESSABLE# */; 


/xx/ 


/x The following errors are generated in DEFSBEAST. */ 
/xx/ 

%~EQU DEFSNO BEAST#H= 103/* DEFSNO BEAST#H */; 

%ZEQU DEFSBEAST_IN CORNER#= 104/* DEFSBEAST_IN CORNER# w/3 


Figure 4-1. Command, Error, HELP Processing Source 


/xM*x DEPSFUZZY_ NODES - This module contains parse nodes for CORNER 
/*x/ 


LT KIKI KIKI HK KKK IKK IKK IKK KKK KIKI IKKAKRKAKRKKKKKKKKKKKKKKKKEKK 
xT * * 
*T* COPYRIGHT, (C) HONEYWELL INFORMATION SYSTEMS INC., 1983 * 
xT* * 
KT KKRKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KKK KKK KKK KKK KKKKKKKKKKKK KEKE / 

/xx/ 

“~INCLUDE DEPSFUZZY _E; 

[xx] 

FUZZY_NODES (HELP_CMD 
QQ_CMD 
QUES CMD 
CLEAN CMD 
QUIT CMD) .EN 

"HELP" JASYM 

tor 

199! 

"CL/EAN' .B ('CO/RNER' | 'HO/USE') 

Cfa/uIT' | 'eEnD' | C*E'-] 'X/IT' ) 


we Me Ve Ve 


o———— 


HELP_CMD(%DEPSHELP_CMD#) 
QUES _CMD(%DEPSQUES CMD#) 
QQ_CMD(ZDEPSQQ_CMD#) 

CLEAN CMD(%DEPSCLEAN CMD#) 
QUIT_CMD(%DEPSQUIT_CMD#) 


Houwow wou 


Figure 4-2. Command Language Definition Nodes 


/xM* DEPSFUZZY_E - This module contains parse %EQUs for CORNER 
/xx/ 


EME SCSES SOS OC SSS S SCS S SCS SSSSTSCLSSCCSCSSOSOSCTSOCSSCCT OCT OCC SC TSS 
xT* * 
*T* COPYRIGHT, (C) HONEYWELL INFORMATION SYSTEMS INC., 1983 * 


xT * * 
KT RK KEKKKKEKKKKKKAKKKKKKKKKKKKKR KKK aKa KKK KKK KKK KKK KKK KEK | 
[x / 

%EQU DEPSHELP_CMD#= 1/* DEPSHELP_CMD# */; 

MEQU DEPSQUES CMDH= 2/* DEPSQUES CMD# */; 

XEQU DEPSQQ _CMD#= 3/* DEPSQQ_CMDA */; 

XEQU DEPSCLEAN CMDH= 4/* DEPSCLEAN CMD# */; 

XEQU DEPSQUIT CMD#= 5/* DEPSQUIT CMD# */; 


Figure 4-3. Command Language Definition EQUs 
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'CORNER. OVER AMBER.CAT 
Corner: THIS IS AN ERROR SINCE I DON'T KNOW WHAT TO SAY 
Eh? 
Corner: ? 
? 22 CL/EAN END HELP Q/UIT 
Corner: CLEAN 
Eh? 
Corner: ? 
CO/RNER HO/USE 
Corner: CLEAN CORNER 
File AMBER.CAT too fuzzy. 
Corner: ? 
File AMBER.CAT is too fuzzy to use as a corner, 
Corner: HELP (BASIC) CAT 
Syntax: 
CATCALOG) CLACCT = account| ACCT=account,ALL]ALL}] 
Corner: @Q 


, 
2 
3 
4 
5 
6 
7 
8 
9 


Figure 4-4. Command, Error, HELP Processing: Sample Session 


'DEFAULT SI=FUZZY,UI=DIGITAL,GN=FUZZY 

!JOB WSN=UPSTAIRS 

'PL6 DEGSBEAST.SI OVER *DEGSBEAST,ME (LS,0U,SCH) 

!'PL6 DEFSCORNER.SI OVER *DEFSCORNER,ME (LS,0U,SCH) 

PARTRGE.X DEPSFUZZY_NODES.SI OVER *DEPSFUZZY_ NODES,ME (LS,0U) 
ILINK *DEGSBEAST,*DEFSCORNER,*DEPSFUZZY NODES OVER CORNER.GN 
'L(C=0) DE?.SI OVER *MODULE_LISTC(LN) "FIND ALL MODULES THAT MAKE ‘CORNER’ 
'€ *MODULE LIST 

IF /../;DE "DON'T BOTHER WITH ‘... nnn FILES' 

IF /DE_ CORNER _HELP/;DE "DON'T include the HELP source 

END 


'SET MSSI .SI 
'SET MSUI UI 
!EXTRACT.X 


DA CORNER.GN 

DFILE 

DA CORNER.GN 

XL *MODULE LIST 

BUILD OVER :ERRCORNER.GN,DE PERR C.SI PRO 

ENO = = 

'R 

IDEL CORNERSDAT,CORNERSTXT FROM .GN "GET RID OF EXTRACT SCRATCH FILES 


Figure 4-5. Command, Error, HELP Processing: Associated Jobs 
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Prompting and Parsing Command Text 


Prompting and parsing are performed by a call to the XURSGETCMD Library 
service. In the DEFSCORNER module (Figure 4-1) the call to XURSGETCMD 
references parse nodes (FUZZY NODES). These nodes coded in PARTRGE 


metalanguage are stored as DEP$FUZZY NODES (Figure 4-2) and created via 
PARTRGE.X (see Figure 4-5). 


The PARTRGE metalanguage to define parse nodes is described in the CP-6 
Monitor Services Reference Manual, Section 10. The XURSGETCMD Library 
service, which uses the X$PARSE service to access the parse nodes, provides a 
consistent user interface in Honeywell-supplied processors. 


The XURSGETCMD service returns in OUTSBLK.CODE a symbol for which the sample 

processor performs the DO CASE statement to cause action appropriate for each 
command. If the command text is illegal, the alternate return is taken with 

an error code set for use by the Library service, XURSERRMSG. 


Syntax Prompting at Syntax Error 


The parse nodes are not only used to parse command text; the nodes can also be 
used to prompt the interactive user by Listing the legal keywords permitted in 
response to the user's entry of ? following a syntax error. XURSGETCMD 
provides this feature by default (it can be overridden by specifying SYNTAX=NO 
when XURSINIT is called). This feature aids the interactive user who is 


unfamiliar with a processor or the experienced user who merely forgets the 
exact command syntax. 


In Figure 4-4 an interactive user enters illegal command text (line 2) which 
is processed by XURS$GETCMD resulting in an alternate return. In the 

PARSE ERROR routine, XURSERRMSG displays the error message (EH?) associated 
with the error code from XURSGETCMD. When the interactive user enters ? (line 
4), the next call to XURSGETCMD interprets this as a request to display all 
keywords or syntax elements permitted at this point and thus Lists all legat 
command names (line 5) obtaining this information from the parse nodes. 


Lines 6 to 8 show a variation of the above steps. In this case, because a 
portion of the command text (CLEAN) is Legal, the XURSERRPTR service is called 
to display an up-arrow at the point where the syntax error occurred. In this 
example at Line 6, the CLEAN command is entered incompletely. Thus in 
response to the user's ? at the syntax error, XURSGETCMD Lists the keywords 
that are permitted following CLEAN, namely CORNER or HOUSE. 
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Displaying Error Messages 


In Figure 4-1 the DEFSCORNER module establishes its error message file name 
with the call to XURSERRMSG. CERRF_FID is defined via the VLP_NAME macro as 
the file called :ERRCORNER.) The :ERRCORNER file is created from error 
message commentary in the CORNER processor (via EXTRACT.X as illustrated in 
Figure 4-5 and discussed in this section in "Creating the Error Message 
File"). When an error condition is detected by the DEGSBEAST module (Figure 
4-1), the XURSERRMSG service passes an error code as an argument. That error 
code, together with the pre-established error file name, allows the Library 
service to perform the error message display. 


The error commentary is coded at the point in the program where the error is 
detected and reported. At that point the value for the specific error (e.g., 
DEGS$TOO FUZZY# for which there is an EQU in DEPS$FUZZY_E) and the severity are 
supplied. 


Other portions of the error code (FCG="DE" and MID="G") are supplied as 
options in the %VLP_ERRCODE. It is assumed that all errors in this module 
have the same FCG and MID. Two levels of complexity are provided by the 
"MESSAGEx:" blocks. Both messages use a substitution “FN that takes the file 
name from the passed error DCB and splices it into the text. Note that the 
substitution is itself bracketed by %s. This requests that none of the 
bracketed material should be printed if the DCB does not contain a name (to 
satisfy FN). In the sample, “FN is satisfied from M$SI. 


The "DESCRIPTION:" block is internal documentation. It can contain any 
information useful to a reader of the source code. Further description of 
error message formats is provided in Section 5. 


In the sample session (Figure 4-4), the error is reported at line 12 with the 
first level message (MESSAGE0Q). When the user enters ? for more information 
about the error, XURSGETCMD is called; the CASE %DEP$QUES CMD is satisfied and 
the XURSMOREMSG service is called. XURSMOREMSG calls either XURSERRMSG or 
XURSHELP depending on which was in control previously. In this case, 
XURSERRMSG takes control and displays the next Level message (MESSAGE1). 


Note: The EH? message displayed at line 8 in Figure 4-4 as a result of a 
parse error is available from a system-standard set of error messages (that 
MSERRMSG uses because the parser's error code contains the XU Function Code 
Group). 


Displaying HELP Messages 


The HELP command, included in the parse nodes as any other command, is 
processed by the DO CASE statement in Figure 4-1 and 


igure results in a call to 


XURSHELP. That service passes the HELP topic and subtopic text to the XSHELP 
library service which performs the HELP message reporting function. 


In Figure 4-4 the sampte session demonstrates that a user can request HELP for 
any other processor and then resume processing in the current processor. A 
HELP file, although not shown for the CORNER processor, could easily be 
provided. Techniques for creating help files are discussed in Section 7, 
"Preparing On-Line (HELP) Documentation". 
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Section 5 


Documenting Source Code 


Extractable Commentary 


Much of the documentation of the CP-6 system is created in source files that 
contain both code and commentary. This means that documentation is kept close 
to the code where it is easy to access and maintain. The commentary not only 
documents the code, but it can also be EXTRACTed (using the EXTRACT processor) 
to produce manual, error message and HELP files. For example, in Appendix A 
of this manual is commentary EXTRACTed from code. 


Structured commentary is used to document CP-6 code as it is written. This 
structure enforces uniformity of documentation as well as providing a 
hierarchy. This hierarchy allows for a gross Level of detail to be given at 
the module or file level, with progressive levels of detail at entry points or 
internal subroutines, for example. Because of this structure, the EXTRACT 
processor can be used to create a hierarchical database of commentary. The 
contents of the database can be used in a variety of forms, giving technical 
documentation without the code. 


Different types of comments document different portions of code. Figure 5-1 
illustrates several comment types. An M type comment, for example, gives a 
one-line overview description of a file, while a D type comment documents 
entry points. Associated with the different type comments are keywords. 

These keywords, used in conjunction with a given type comment, insure full 
documentation of a block of code. For example, when documenting an entry 
point with a D type comment the keywords used are CALL (where form of the call 
is given), PARAMETERS (where the parameters of the call are described), etc. 
Certain keywords can be selected for inclusion in EXTRACT reports. 
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/*M*k FOOSOUTSYM Main routine for OUTSYM ghost */ 
LT HK IK i KK I KK KK KK I II KIT KK I KK II KKK IKK KKK KK KKK KKKKKKKKKKKKKK KKK 

kT * * 

*Tx COPYRIGHT, (C) HONEYWELL INFORMATION SYSTEMS INC., 1980 * 

xT * * 

KT KH KK KKK KKK IK KKK KK KIKI KKK KKK KK KK KHAKI KKKKKKKK KK KKK KKRKKKK KKK / 
/*X* DMC,PLM=6,IND=0,IDT=2,SD1=2,CTI=0, ENU=0,AND,D0CI=4,CSU=2,...%/ 
[xx / 

/x*Px NAME: FOOSOUTSYM 


COON AMUEWDN = 


PURPOSE: To provide the main routine for the OUTSYM ghost. 


DESCRIPTION: FOOSOUTSYM is the main routine for the OUTSYM 
ghost, which provides and/or controls all the 
CP-6 output symbiont functions performed in the 
host. 


688 /*D* NAME: EXT EVENT 
689 PURPOSE: To process an external event 
690 DESCRIPTION: EVNT$S points to an FOSEVNT frame, in which is a 


691 code, and a possible CITES pointing to an FOSCITE 
692 frame. 
693 


SCREECH CODE: FOO-SSNODEV 
TYPE: SNAP 
MESSAGE: Event reported on non-existent device 
REMARKS: A disconnect, break, or similar event has 
been reported, but the named device 
cannot be found. x/ 


Figure 5-1. Source File Containing EXTRACTable Commentary 


From the code shown in Figure 5-1 a programmer could, for example, use EXTRACT 
to create a report of all *M* comments, or a report of all *P* and *D* 
comments, or a separate file of screech codes from all *S* comments. 
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Commentary Rules 


The following rules apply to producing commentary in an extractable form: 


1. 


2. 
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Commentary should not be on the same Line as code. 


To allow EXTRACT to identify commentary in various types of source files, 
it is necessary for the first non-blank source Line to conform to these 
requirements: 


Language First non-blank source Line must contain: 

PL6 /*x or ; in any column(s) 

FORTRAN C in column 1 

BASIC REM starting in column 1 (see NOTE) 
APL $COM starting in column 1 

IBEX i or: starting in column 1 

TEXT - (period) in column 1 

IDOL eee (dashes) starting in column 1 

other x in column 1 or 7 


For example, a PL6 program starting with 
PROC 
is interpreted as a FORTRAN program. 


NOTE: For BASIC programs the first record must not have a Line number. 
EXTRACT skips line numbers of subsequent records. 


The syntax for a comment is of the form: 
C{cmtstart}{cmttype} Cx] {text} {cmtend} 


The text can be any sequence of ASCII characters except {cmtend}. For 
example, a PL6 comment appears as 


/xM*x FOOSOUTSYM Main routine for OUTSYM ghost */ 
where */ is not permitted with in the text string. 


If C(cmtstart} does not end with *, then the programmer must supply *. For 
example, an M comment in FORTRAN would be coded as 


CxM*text 


Comments can extend to the maximum record Length (e.g., 140 for PL6, 80 
for FORTRAN). 


Comments may be continued over a number of records. In PL6, comments may 
be continued without a /* in front of each record. However, the Last line 
in a block of commentary must be terminated with a */. 


In non-PL6 code, lines that are continuations of a previous commented Line 
must include either a comma as the comment type or the same letter as the 
comment type. Using the same comment type but repeating the previously 
used keyword begins a new comment, as illustrated in the following 
examples. 


Examples: 


*M*x EXAMPLE This is an example of non-PL6 code 


xT* eaeoeaoasese 

*Px NAME: EXAMPLE of non-PL6 extract code 

x ,* so that EXTRACT knows this belongs 
x ,* with the 'P* comment, we use ',' 


IN 


ENTDEF EXTRACT 
SYMDEF wecaaes 


a,* This also belongs to the 'P'comment 
*D* NAME: This 78 a new comment type ‘'D' 

x,t Second line of type ‘'pD' 

xD* Third line of type 'D' 


*D* NAME: New type 'D' comment 


*D* NAME: Another new 'D' comment 
*,* Some more of the 'D' comment 


6. Upper and lower case letters should be used to make commentary more 
readable. 


7. ‘Keywords must include a final colon (:), e.g., PURPOSE: 


"Commentary Tools" in this section discusses a processor that formats 
commentary to these standards. Conventions to follow in placement of 
commentary within a file are also discussed later in this section. 


Comment Types 


Table 5-1 gives a summary of the different comment types that can be used 
documenting a file. 


Table 5-1. Summary of Commentary Types 


Description 


Data definitions. 


Detail on ENTRY points, PROCS and macros. 


Error message. 


Preamble or overview for a routine or ENTRY point. 


Detail on internal subroutine. 


Keyword definition or data description. 
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when 


Table 5-1. Summary of Commentary Types (cont.) 


Description 


One-line description of a file. 


Denotes that code is to be added for a deferred feature. 


Message to system operator. 


Preamble or overview for a module or function. 


Screech code message. 


Denotes that copyright notice is to be inserted by FORMAT or 
PL6FMT. ; 


Gives warning and explanation of error codes, also describes 
bugs and/or inefficiencies. 


Source formatting controls used by FORMAT or PL6FMT. 
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M Comments 


Description: 


A type *M* comment is a one-line description of a file. There should only be 


one *M* comment in a file and it must be the first Line of the file. 


Format: 


/*M*k name - description */ 


Example: 


/*M*x PAYROLL - Program that computes employee payroll and taxes.*/ 


P and F Comments 


Description: 


*Px and *F* comments are preambles or overviews. A *P* iS a preamble to a 
file; *F* is a preamble to a routine or entry point. The preambles are 
descriptions that include significant features or Limitations of a file or 
routine, but do not include details. 


Keywords: 


The following keywords may be used in conjunction with *P* and *F* comments: 


Keyword Description 


NAME: 


The first record of any group of *P* or *F*x comments must be 


the NAME keyword. The name should be the file name for *Px* 


and the PROC/ENTRY name for *Fxe, 


PURPOSE: 


Describes the purpose of the file, routine, or entry point. 


DESCRIPTION: 


Describes the function and special features which this module 


performs. 


REFERENCE: 


Gives a cross-reference to manuals and/or other reports or 
documents. 
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D Comments 


Description: 


Type D comments give detailed description and should be inserted for every 
entry point, including the PROC statement. Descriptive *D* comments may be 
interspersed with the code to explain individual Lines or blocks of code. The 
*D* comments appear at the point of entry rather than the front of a module. 
They include the information necessary for the user to know how to use the 
routine and what to expect of it in the way of usage, interfaces, input, 
output, etc. These comments will be collected by EXTRACT and included in the 
*D*x (detail) report. If a routine contains more than one entry point with 
similar details, only the first *D* comment needs to include full description 
for each keyword; only the keyword ENTRY: and any differences need be 
specified on *D* comments for Later entry points. 


Keywords: 


The following keywords may be used in conjunction with *D* comments: 


Keyword Description 


NAME: 


Defines an entry point. It must be the first record of.a 
group of *D* comments. The name is used for sorting. 


ENTRY: 


Needed only if multiple entries require the same detail 
report. If a routine contains two entry points which are 
conceptually alike, the programmer, when documenting the 
second entry point need only enter NAME:, ENTRY: and the 
keywords and paragraphs which distinguish the second entry 
point from the first. This saves the programmer a Lot of 
typing because the EXTRACT processor then copies the common 
fields from the first entry point into the second entry point. 


CALL: 


Gives the calling sequence for this routine, including the 
alternate return CALTRET), if used. 


PARAMETERS: 


Describes parameters of the call. This field along with the 
CALL commentary should be sufficient to describe how to invoke 
the routine. 


INTERFACE: 


Lists routines that this routine calls and routines that can 
call this one. Describes declaration of external entry 
points. Also lists any INCLUDE files needed to use this 
routine. 
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Keyword 


Description 


ENVIRONMENT: 


Describes anything special about how to run this routine such 
as mapped/unmapped, master/slave, file authorization required 
(privileges), inhibit or not, etc. 


INPUT: 
Data accessed (external as opposed to global) to perform a 
function. Can also list the inputs from the calling sequence. 
OUTPUT: 
Data altered and intended as the result of this 
operation/routine. Can also List the outputs of the calling 
sequence. 
SCRATCH: 


Data altered but not intended as results (side effects). 


DESCRIPTION: 


Describes what the routine does and how it functions. 


ALTRETURN: 
Describes the conditions which cause an alternate return, if 
the routine is defined with the ALTRET option. 
Example: 
/*D* NAME: ZYFSCALL BUILTIN FUNC 
CALL: CALL ZYF$CALL_BUILTIN FUNC (V_RESULT, 
= BUILTIN ID,ARG_ COUNT,V_ARG LIST) ALTRETCERR); 
INPUTS: BUILTIN ID, UBIN - ZEQUs are in MIIL definition. 
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ARG COUNT, UBIN - actual number of arguments 
provided. 
V_ARG LIST - array of up to 63 "values" representing 
the arguments. 
OUTPUTS: V_RESULT - a "value" representing the function result. 
DESCRIPTION: Verify the argument count and call the proper 
routine to do the real work. 
If trouble is encountered, a diagnostic will be 
issued and a default value of the appropriate type 
will be returned to minimize later confusion. 
ALTRETURN: If a non-recoverable difficulty is detected. */ 
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B Comments 


Description: 


*xBx comments are data definitions. All external data bases must contain a 
definition for each field. The *B*x comment must follow the field it 


describes. 


Format: 


/*Bx name - description 


x/ 


| Comments 


Description: 


*I* comments describe internal subroutines with no external calls. 


Keywords: 


The following keywords may be used in conjunction with *I* comments: 


Keyword 


NAME: 


PURPOSE: 


CALL: 


PARAMETERS: 


DATA: 


DESCRIPTION: 
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Description 


Defines the name of an internal subroutine. The first record 
of a *I* group must be the NAME keyword. 


Describes the function performed by this internal module. 


Documents the calling sequence. Also discussed here are the 
means by which this routine could altreturn, if possible. 


Lists and describes the input and output parameters. 


Describes any additional data which might be required by this 
routine. An example would be the use of globals. 


Describes what this routine does, how it functions, and the 
details of its purpose. 


WW 
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I Comments 


Example: 


[x Ix NAME: CHECK 
PURPOSE: Check that an acceptable number of arguments 


has been specified. 
Print message and ALTRETURN if not. 


INPUTS: WANT, UBIN ~ number of arguments function 


wants. 163 is a special case for 
minimum/maximum who can handle 1 thru 63. 
NAME ~- name of function followed by ‘'.' 


DESCRIPTION: It would be a whole lot easier to have constant 


*/ 


E Comments 


Description: 


*Ex comments 
The comments 


arrays containing the textual representations 
and number of arguments expected but this 
introduces maintenance problems. 


are used to create error message files and manual appendixes. 
should describe what went wrong to cause delivery of this 


message. These comment Lines appear in the Listings at the point of first 


occurrence, 
The comment 
error condit 


since multiple uses of one error code and message are possible. 
should include the error code, if any, and a description of the 
ion. Further discussion of error message reporting is included 


elsewhere in this manual. 


Keywords: 


The following keywords may be used in conjunction with *E* comments: 
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Keyword 


ERROR: 


MESSAGE: 


MESSAGEO: 


MESSAGE1: 


DESCRIPTION: 


Description 


This is the error code consisting of the FCG (Functional Code 
Group), MID, MON, error code, and severity level (e.g., 
FMA-ESEOF-3). An EQU should also be made to relate this error 
comment to itS appropriate call. The ERROR: keyword must be 
the first record of the group. 


Contains the actual text of the error message. This field 
must not be used with the numbered message fields. 


This field contains the first level of a description of what 
the error is. It is used in conjunction with at least one of 
the following MESSAGEn fields. This field should not be used 
with the unnumbered message field. 


This is the next Level of error message, to be displayed after 
a user types a ? after receiving MESSAGEO. Additional 
keywords, MESSAGE2, MESSAGE3, ..., MESSAGE7, may be specified. 


This field is used as an aid to the programmer to describe how 
this error can occur, a possible work around, and a means by 
which the error might become eliminated in the future. It is 
never delivered with the error message. 


E Comments 5-11 


W Comments 


Description: 


A *W* comment can be used anywhere in a file to describe a block of code, its 
possible bugs and/or inefficiencies. It is also used to give warnings to the 
programmer or to explain problems. 


Format: 


/xWe commentary 
* / 


S Comments 


Description: 


*S* comments are used to create the Screech code message file and manual 
appendixes. These comments are included where a Screech condition occurs. 
EXTRACT will supply the filename for the "REPORTED BY" keyword. 


Keywords: 


The following keywords may be used in conjunction with *S* comments: 


Keywords Description 


SCREECH CODE: 


Screech code to identify the condition (e.g., FOF-SSOFFADD). 
The SCREECH CODE: keyword must be the first record of the 
group. 


TYPE: 

Screech, SUA (Single User Abort), or SNAP 
MESSAGE: 

Explanation of what caused the Screech. 
REMARKS: 


Further description of the cause. 
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Example: 


/*S* SCREECH CODE: FOF-SSOFFADD 


TYPE: SNAP 

MESSAGE: A batch job added a file to OUTSYM after 
going OFF. 

REMARKS: OUTSYM receives an event from MONKEY 


whenever a batch job leaves the system. 
This SCREECH occurs when OUTSYM receives 
an output file add from a batch job which 
has been marked off. This means that 
OUTSYM or the monitor is very confused 
about that job. 

x/ 


K Comments 


Description: 

The *K* may be used for keyword definitions or for data descriptions to be 
extracted as user documentation. 

Format: 


/*K* name - definition or description 
x / 


O Comments 


Description: 

A *0* comment is a message to the system operator. Properly formatted, it 
will provide the appendix to the operators manual; thus keywords are 
important. A *O0* comment should appear in code wherever an operator message 
is reported. 


Keywords: 


The following keywords may be used in conjunction with *0* comments: 


Keyword Description 


MESSAGE: 

Contains the actual text of the message. 
ACTIONS: 

Instructs the operator on the course of action to take. 
MEANING: 


Describes the message in detail. 


T Comments 


Description: 

A *T* comment is placed at the point in a file where the Honeywell copyright 
notice will be inserted. This comment does not have to be inserted by the 
programmer. It is inserted by FORMAT.X or other services, prior to the 


program files' release. By convention, the *T* comment is placed after the 
xM*x comment at the head of a file. 


Format: 


/xT*/ 


N Comments 


Description: 
*N* comments are placed at a point in a file where code is to be added at a 


future date. They can also be used to identify minor features that are not 
supported as a reminder to the module owner. 


Format: 


/*N* keyword ~- description 
*/ 
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X Comments 


Description: 


*xX* comments are used to place PL6 format controls ina file. These comments 
may be placed at any point in a file, and may be used numerous times. The 
last encountered set of format commands are the ones followed when formatting. 
A full description of the format commands appears in in the PL~6 Reference 
Manual (CE44), "Format Facility". 


Format: 


/*X*x (format option),(Coption), ... 
* / 


Placement of Commentary in a File 


Certain comment types are intended for the beginning of modules and routines; 
others comment types are embedded in the code at the point of significance. 
Figure 5-2 illustrates where to include each comment type ina file. The 
notes following each comment describe how the different comment types are 
used. 
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/*M* Me, *T*, *X* and *P* comments occur once 
/xTx at the beginning of a file. *P* comments 


[xX describe the function of a file. 
/xPx 


[xDx *D* comments can be used to document the 
4MACRO details of a macro. 
4MEND; 


/* Fe *Fe and *D* comments are used to indicate 
/xDx a procedure or entry point ina file. They 
A: PROC; may appear any number of times. 


[*K* *K* and *Bx comments are used to define data 
/*Be types. 
DCLs 


/xFFe 
[xD 
B: ENTRY; 


/*N* Ne, *O*%, *Sk, kWe and *E*x comments may 


*O* appear at any appropriate point ina file. 
xS* 


x We 
xEx x/ 
CODE FOR MAIN PROGRAM; 


/xI* x/ 
Routine internal to this PROC; 
END A; 


%4E0D; ZEOD indicates the start of a new procedure. 
/* Fe x/ 

/xDx */ 

Z: PROC; 


/x Ix x/ 
Routine internal to this PROC; 
END Z; 


%EOD; 


Figure 5-2. Placement of Commentary in Source Code File 
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Commentary Tools 


The X Account provides a multitude of tools which assist the user in 
formatting and updating commentary, extracting commentary into a database and 
exercising the database. Two of the more useful tools (EDICT.X and EXTRACT.X) 
are described briefly below. For more information on available tools please 
see Section 3, "Programmer Aids" and "Documentation Aids." 


EDICT.X 


EDICT.X is an interactive tool which formats commentary into an extractable 
form. EDICT.X formats commentary, supplies keywords, allows use of EDIT 
features, etc. For more information, invoke EDICT.X and request HELP within 
that processor. 


EXTRACT.X 


The EXTRACT processor extracts error messages and commentary from source code 
into a data base which then can be used to create Error Message files, HELP 
files and Reference Manual files (portions of the Monitor Services Reference 
Manual, for example). 


Text Blocking in Extractable Commentary 


A double colon can be placed after a Keyword to cause EXTRACT to block the 
text on the left margin. A single colon tells EXTRACT to indent the text. 
Example 1: 


The following example illustrates what the output would look Like if a single 
colon is used after the keyword: 


Keyword: The text will be EXTRACTed 
in a block format like this 
when a single colon is used. 


Example 2: 


The following example illustrates what the output would Look like if a double 
colon is used after the keyword: 


Keyword: The text will be EXTRACTed in a block format Like this when a 
double colon is used. 
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Sample EXTRACT.X Job 


The EXTRACT processor provides a number of commands to request extracting and 
formatting of specific types of commentary. In addition, certain commands 
also perform alphabetical sorting to generate easy-to-use reports. See HELP 
CEXTRACT.X) for more information. Figure 5-3 shows a sample use of EXTRACT: 
source file commentary is first displayed; an EXTRACT job using the DOC 
command (Cand others) is performed. Figure 5-4 shows the resulting document 
processed by TEXT, illustrating the commentary sorting, formatting, and 
addition of page headers and footers performed by EXTRACT.X. 


!C EDICT SOURCE 
/xMk EDICT - EXTRACTABLE DOCUMENTATION IN CRISMAN TERMS */ 
DT HR RRO OO IO III IO IO tok tok tok tok tok tok kkk tek / 
/*T* */ 
/xT* COPYRIGHT, (C) HONEYWELL INFORMATION SYSTEMS INC., 1983 */ 
1*xT* x/ 
LT KEK KKK KKKKKKKKK KKK KKK KKKKKKKKKKKKKKKK KKK / 
[xXx PLM=2,STI=2, IND=2,CTI=4,DC1I=5,PRB=YES,ECI=3,CS1=3,THI=2, 
IAD=2,DIN=2,ENI=4,CLM=0,CCC,MER=NO,CCE,SQB=YES,MCI=YES */ 
[xPx 
NAME: Document 
PURPOSE: 
This program prompts the user for input for the *Mx *Px xFe 
xI* *D* program documentation standards. 
DESCRIPTION: 
Using standard invocation syntax this program creates a 
separate file containing the document material. 
This documentation was created with this program! 
REFERENCE: 
Any problems? see gary palmer . 


NAME: Promptfile 
PURPOSE: 


This routine does the structuring of the *M* document, since 


CALL: 
Call promptfile; 
DATA: 
This routine also structures the *P* document section. 
DESCRIPTION: 
Create the *M* and *P* documents. Then ask if you want to 
document a module. 


NAME: Dotext 
PURPOSE: 
Does the body of text for any subsection of a document type. For 


example: it would create the paragraph/s for purpose or call. 
CALL: 


Call DOTEXTCHEAD,P_FLEG); 
PARAMETERS: 
HEAD: Name of the subsection we are documenting. Required parameter. 


P_FLAG: Indicate whether this is a required section or not. Optional 
DATA: 


None. 
DESCRIPTION: 


Sets up the section defined by head, if the input is nil and this is 


Figure 5-3. Sample EXTRACT.X Job (cont. next page) 
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x / 

EDICT: PROC MAIN; 
“INCLUDE CP 6; 
“INCLUDE BSJIT; 
%INCLUDE B_ERRORS C; 


'XEQ EX EDICT JOB 
$J0OB ~ 
S$RESOURCE TIME=1,MEM=216 
SDONT ECHO 
File EDICT DOC does not exist 
CP~6 EXTRACT Version BO3 - February 1982 


DA EX 
New Data Base - EX.SAMPLE 
EX EDICT SOURCE 
Extracting from - EDICT _SOURCE.SAMPLE 
DOC ME,EDICT DOC 
SECTION=EDICT 
HEADING=DOCUMENTATION FOR EDICT.X 
9 
Document file EDICT DOC Created. 
10 Records in Data Base EX.SAMPLE - Saved. 
Good Bye. 


> 
> 
> 
> 
> 
> 


EXSDAT EXSTXT 
2 files, 8 granules deleted 
> TEXT EDICT DOC TO LP 
DATA IGNORED: 
1 records ignored 


“Figure 5-3. Sample EXTRACT.X Job 
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DOCUMENTATION FOR EDICT.X 
EDICT SOURCE 


00009 


NAME: Document 
PURPOSE: This program prompts the user for input for the *Mx *Px 
xFe Ie *D* program documentation standards. 
DESCRIPTION: Using standard invocation syntax this program 
creates a separate file containing the document 


material. This documentation was created with this 
program! 
REFERENCE: Any problems? see gary palmer 


00100 
NAME: Dotext 
PURPOSE: Does the body of text for any subsection 
of a document type. For example: it would 
create the paragraph/s for purpose or call. 
CALL: Call DOTEXTCHEAD,P _FLEG); 
PARAMETERS: HEAD: Name of the subsection we are 
documenting. Required parameter. 
P_FLAG: Indicate whether this is a 
required section or not. Optional 
DATA: None. 
DESCRIPTION: Sets up the section defined by head, 


—_—_—— 


COPYRIGHT, (C) HONEYWELL INFORMATION SYSTEMS INC., 1983 


EDICT-1 


DOCUMENTATION FOR EDICT.X 
EDICT SOURCE 


00021 
NAME: Promptfile 


PURPOSE: This routine does the structuring of the 


CALL: Call promptfile; 
DATA: This routine also structures the *P* 
document section. 

DESCRIPTION: Create the *M* and *P*x documents. 

Then ask if you want to document a 

module. 


EDICT-2 


Figure 5-4. TEXTed Document of EXTRACTed Commentary 
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Section 6 


Error Message Reporting 


The CP-6 system provides a centralized facility for the storage, selection and 
delivery of error messages. A monitor service, X account tool, library 
routine and set of standards provide an easy and uniform access to error 
messages. 


Error Message Source 


CP-6 error messages are embedded in source code as type E comments. The error 
messages are placed in the code directly after the call to MSERRMSG. These 
comments document the code and are also used to create error message files. 
Figure 4-1 shown earlier in this manual illustrates the error message source 
format. 


Error messages should provide the user with meaningful as well as accurate 
information. Therefore, messages should be a sentence that is specific and 
clear. Substitution fields (discussed later) should be used frequently.to 
provide the user with as much detailed information as is possible. The error 
encountered should be specifically referenced. Layered messages, to be 
displayed successively at the request, should expound on the causes and cures 
of the error. 


Error Codes 


Each error message is associated with a standard CP-6 error code. The code is 
split into four sections: the FCG, the MID, the MON and SEV. The FCG, or 
Functional Code Group, is a two-character alphabetic field which indicates 
which processor or portion of the operating system is reporting or has 
detected the error. MID is a character that indicates which module of the 
processor detected the error. MON determines whether or not the message came 
from the monitor. Error number is a number that distinguishes a particular 
error from others with the same FCG, MID, and MON. 


The last field, SEV, serves two purposes: 


1. It indicates which Level of message complexity is desired when part of a 
code is passed to MSERRMSG. 


2. It determines what will happen to a caller when part of a monitor service 


call does not have an ALTRET. For more information see the description of 
MSMERC in the Monitor Services Reference Manual. 


Example: 
DEG-ESFUZZERR-2 
where 


DE specifies the FCG. This field may be blank. 
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G specifies the MID. This field may be blank. 


ESFUZZERR is the particular name or 1~to-4 digit number unique to this 


particular error. If a name is specified, an EQU must be included to define 
the error number, 


2 specifies the severity of the error. 


Layers of Error Messages 


CP-6 error messages may have up to eight levels. The text of the message(s) 
is specified following in *E* commentary following the keyword MESSAGE if a 
single level is used, or following the keywords MESSAGEO, MESSAGE, ... 
»MESSAGE6, MESSAGE7 if multiple levels are used. The contents of each level, 
up to but not including the highest one used, may be built upon the Lower 
levels. Each message has different levels of complexity with the lLowest-level 
message being short and to the point and each successive message elaborating 
on causes and cures. 


The highest Level of error message must be self-contained since it is the only 
message that a batch user receives. The environment at the time of the error 
dictates which message is to be printed for a specific error. Interactive, 
time-sharing users are given the lLowest-level (least verbose) message. The 
user can enter "2?" to obtain the next level of message. This continues until 
the user figures out the problem, or the messages are exhausted. A second 
construct, "22", displays all remaining messages in order of ascending 
complexity. Batch users are unable to request additional error messages since 
the command stream was written before the occurrence of the error. To 
accommodate them, the highest available Level of message is displayed. 


The selection of the original level and processing of the ?/?? commands takes 
a moderate amount of code. To save code and enforce consistent treatment, 
library routines are provided for the message display and subsequent 
elaborations. For details, please see the documentation for XURSERRMSG, 
XURSMOREMSG and XURSALLMSG in the Monitor Services Reference Manual. 


Field and Phrase Substitution 


An error message consists of one or more Lines of text with optional 
substitution fields. Substitution fields allow a canned message to be made 
specific with details about the causes of the error. AS an example, the 
monitor message for "file does not exist" actually gives the name of the 
offending file. This technique is discussed under "Field and Phrase 
Substitution" in the MSERRMSG section of the Monitor Services Reference 
Manual. 
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Default Error Messages 


Default error messages can be defined pertaining to: 


e ALl occurrences of the same error condition within all modules in a 
Functional Code Group. In this case the Module ID is set to NIL. 


e ALl occurrences of the same error condition within all Functional Code 
Groups in the user procedure. In this case the Functional Code Group and 
Module ID are set to NIL. 


When the requested error message is not available, MSERRMSG can go to great 
Lengths in search of a suitable substitute. The method used by MSERRMSG to 
determine which message to display is discussed in Monitor Services Reference 
Manual in the SUBMESS Option subheading following the description of the 
MSERRMSG service. 


Examining the Error Code After Monitor Service ALTRET 


If the caller has not aborted, the error code can be examined in the ALTRET 
frame. The entire standard error code fits into a single 36-bit word. The 
structure is described under VLP_ERRCODE in the Monitor Services Reference 
Manual. For more information on accessing the TCB see Section 8, "Accessing 
the TCB." 


Creating the Error Message File 


The EXTRACT.X processor can be invoked to create a data base of commentary, 
and to build an error message file in the format required (Ci.e., a file that 
is keyed by the modified error code). Although MSERRMSG can access an error 
message file with any specified name, EXTRACT will supply default names for 
error message files it creates based on the FCG and MON. 


Figure 6-1 illustrates a job that creates an error message file named in 
Figure 4-1. 
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1.000 !L(C=0) DE?.SI OVER *LIST(LN) 
2.000 !€ *LIST 

3.000 IF /../3;DE 

4.000 FD 0-99999.999,/DE CORNER HELP/ 
5.000 !SET MS$SI .SI 

6.000 !SET M$UI .UI 

7.000 !EXTRACT.X 

8.000 DA CORNER 

9.000 DFILE 

10.000 DA CORNER 

11.000 XL *LIST 

12.000 BUILD OVER :ERRCORNER PRO 
13.000 END 

14.000 !R 

15.000 !DEL CORNERSDAT,CORNERSTXT 


Notes 


e Prior to calling EXTRACT, use the List command to place names of all the 
modules with the FCG of DE into *LIST (line 1) Using EDIT, delete from 
*LIST all Lines containing ".. nm FILES LISTED" and the HELP source file 
which contains no error messages (lines 2-4). 


Specify the accounts from which the source and update files named in *LIST 
are to come (lines 5-6). 


Invoke EXTRACT.X (Cline 7), establish the prefix for the names of the work 
files Cline 8), delete any old work files (DFILE at Line 9), reestablish 
the prefix for work file names (line 10), create a data base of commentary 
from the files named in *LIST (line 11), and build the error message file 
Cline 12) in the format required by MSERRMSG. 


Figure 6-1. Sample Job to Create Error Message File 


Foreign Language Error Message Files 


The CP-6 error-message system supports messages in various languages. Each 
user's JIT contains a one-byte value determined by his declared native 
Language. This byte is appended to the name used by MSERRMSG in opening the 
message file, so supporting a new Language is as simple as placing translated 
messages into a file with the appropriate name. More information on this 
feature and the naming convention for error message files can be found in the 
Monitor Services Reference Manual under the FILENAME parameter description of 
MSERRMSG. 
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Finding the Error Message File 


When calling the MSERRMSG monitor service, a programmer must supply the name 
and account of the appropriate error message file. If the program and its 
error message file can be assumed to be in the same account, the program can 
obtain the account as follows. Every running program has DCB M$LM associated 
with it as DCB #2. The progran can find what its name is by accessing the 
DCBN.NAME#.C field, and its account by accessing DCBN.ACCT#. The DCBN.ACCT# 
can be specified as the account on the call to MSERRMSG. As Long as the error 
message file and the run unit are transported to different accounts as a set, 
the error message file can always be found. 
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Section 7 
User Documentation/HELP 


STEXT Facility 


The CP-6 user documentation -- including this Guide -- is created via the 
STEXT.:DOCUM facility. This facility can produce several forms of 
documentation from source text files: hard-copy documents, document 
unit-record files for electronic distribution, and HELP files. 


$TEXT capabilities include: 


Assembly of complete manuals from multiple files. 

Automatic generation of title page, table of contents, and index. 
Automatic layout of headings, tables, and figures. 

Generation of HELP files from source text files. 


Following the conventions discussed in this section assures device-independent 
output for hard-copy and HELP files. 


Files that can be processed by $TEXT are keyed files built via EDIT. The 
files contain text, plus TEXT control words and macro control words. Once 
source text files are built, compiling a complete document is a fast, simple 
process. "Document assembly" can be requested through a menu-driven interface 
described in this section. The same interface allows creation of a HELP fite; 
see “Preparing On-Line (HELP) Documentation" in this section for details. 


The tools for the user of $TEXT include: 


e The EDIT processor to build source text files. 

e The menu-driven interface, STEXT.:DOCUM (which uses SFASTEXT.:DOCUM and 
invokes the TEXT processor). 

e Macros which are stored in :LIBRARY (e.g., :MAT.:LIBRARY). 


Conventions for text source files are highlighted in this section. A full 
description of $TEXT capabilities is provided in guide CE59. Full information 
on TEXT is provided in the CP-6 Text Processing Reference Manual (CE48); a 
HELP file is also available. In addition, the CP-6 Text Processing 
Administrator Guide (CE52) contains related information. 
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File Naming Conventions 


File naming convention are crucial to document assembly. Source text file 
names must be of the form: CEdocnum_secnum or HAdocnum_secnum. For example, 
the file CE40 01 is manual CE40, section 1. The section number is used during 
document assembly to order the files. The section numbers are organized as 
follows: 


Section Number File Identified 


00 The front matter section, which contains the 
following standard introductory material: 
the Preface, Title Page, a call to the 
Table of Contents file, About This Manual, 
and the Syntax Notation page. 


01 thru 49 The numbered document sections. 
50 thru 59 The appendixes. 
90 The glossary. 


Table of Contents and Index files are created and included in a hard-copy 
manual during document assembly. 


NOTE: After processing by $TEXT, the resulting document may be printed in 
hard copy form or stored in one unit record file (from which multiple copies 
could be made). The name for such a unit record file may be any legal FID. 


Document Assembly 


The user can initiate a dialog with $TEXT during which it prompts the user for 
all the information required to perform document assembly. 


To begin the document assembly dialog with STEXT, the user enters the 
following: 


'XEQ STEXT.:DOCUM 
$TEXT responds with: The user enters: 


FASTEXT B03 


Files to Format> The names of the files to be printed. 
A wildcarded file name in the 
form prefix? is specified to 
identify multiple files. 


In Account> The name of the account in which 
the files reside. 


Device or Destination> The location of the file or 
printer device to which the 
output is to be routed. 


TEXT Options> The options to be used to format 
the document. 


DRAFT or FINAL Format> The format to be used for the 
document. 


Pagesize (type of paper)> The type of paper that the 
document is to be printed on. 


Number of Copies> The number of hard copies desired. 
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Extra Files> Whether to generate a table of 
contents, an index, and/or a 
typeset header file as part 
of the document assembly. 


Go for It?> Whether to begin the assembly 
process, initiate a response 
change mode, or terminate 
document assembly. 


ALL user responses are followed by a <CR>. For all prompts, there is a 
default. The user selects the default by entering <CR> only. Typing HELP<CR> 
in response to any prompt (except "Go for it") displays appropriate responses 
to the prompt. For complete information on document assembly, please see 
CES5S9. 


Summary of Control Words and Macros 


Text source files contain text, TEXT control words, and macro control words. 
TEXT control words regulate indentation, spacing, etc. The macros control 
placement and underlining of section and subsection headings, positioning of 
headings and table columns, positioning of figure and table headings, and 
identification of index entries. 


Each control word or macro is placed on a Line by itself, beginning in the 
first character position of the line. Control words begin with a period in 
position 1. Macros begin with periods in positions 1-2. Table 7-1 summarizes 
the subset of TEXT control words frequently used in files processed by STEXT. 
Table 7-2 summarizes the frequently used macros recognized by $TEXT. 


Table 7-1. TEXT Control Word Summary 


Control Word Description 


-SPB Cn] 
Creates n blank Line(€s), where a page break is acceptable 
-SPF En] 
Creates n blank Line(€s), where a page break is unacceptable 
-FIF 
Causes the following copy to appear on output exactly as it is 
entered in the file 
~FIN 
Causes text formatting to resume. That is, after a .FIF and 
portion of text to be output exactly as entered in the file, 
-FIN causes text to fill full Lines in the output produced. 
eINL n 


Indents the following text Lines by n positions 
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Table 7-1. TEXT Control Word Summary (Ccont.) 


Control Word Description 


e-UNL n 


Starts the following Line n positions to the left from the 
indent position specified by the previous .~inl control word 


-BRP 


In files to be processed by $TEXT, "break page” (.BRP) is 
restricted to use in the end-of-file sequence. ($TEXT 
performs page layout.) 


eSRV name expr 


In files to be processed by $TEXT, 


-SRV SECTION {n|"x"} 


creates the section or appendix identifier for use on page 1, 
in page numbering, and in the table of contents. The 
identifier is a number for sections, a letter for appendixes 
Ce.g., "A"), or "g" for a glossary. 


TRF xy 


Translates character x to character y until the next .trf 
control word is encountered. $TEXT assumes that the character 
“is to be translated to a blank (Ci.e., it assumes .TRF * ) 
except in figures. 


Table 7-2. Macro Summary 


Macro Description 


»-2LlOH 


“head” 


Creates a section name. 


oe2tL€1/2/3/43H “head£shelp_ infol" 


Creates a subsection head of level 1-4, formatted according to 
$TEXT conventions. For levels 1-3, creates an entry in the table 
of contents and index, if requested. By default, creates a HELP 
topic of tevel 1-3 heads with associated level 4 heads as 
subtopics. 
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Table 7-2. Macro Summary (cont.) 


Macro Description 


--:MAT “table info” 


Creates a table from subsequent text, controlling spacing before 
and after the table, table title, table headings, and table layout. 
Table types are as follows: matrix, 2-column formatted, and 
unformatted. Also creates an entry in the List of tables, if a 
table of contents is requested. 


Terminates table text. 


ee:FIG “fig info" 


Creates a figure from subsequent text, controlling spacing before 
and after the figure, placement of figure title, and layout. Also 


creates an entry in the List of figures, if the table of contents 
is requested. 


2e:IDX “index info" 


Creates an index entry for a term included or implied in the 
preceding text. 


"Cmanual_text]Cjhelp_textl]" 


Creates alternate wording for the manual and for the HELP file. 


Creating Text Source Files 


This subsection describes conventions for creating a text source file for 
hard-copy documentation. Guidelines for producing on-line HELP files from the 
same files are discussed in a later subsection. 
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Line Length 


In general, it is advisable to keep Line length to a maximum of 79 characters. 
In unformatted copy-- such as figures, unformatted tables, or matrix tables-- 

Line Length must not exceed the page width. Length restrictions are stated in 
"Usage Notes" in the discussion of the macros for tables and figures. 


HELP files must not include Lines of greater than 79 characters. This can be 
accomplished by entering text according to the guidelines stated above and by 
Limiting :HLP macro lines to 79 characters. In generating a HELP file, a 
warning is issued for records exceeding 79 characters. NOTE: Overstriking 
counts as two characters (backspace, and the overstrike character), and should 
be avoided in text that is to appear in HELP files. 


Blocking 


$TEXT assumes that text is blocked. That means that all paragraphs start on 
the left margin. Lists do too, unless they are Lists within Lists. 


Indentation of List text is accomplished by use of the TEXT control words .INL 
and .UNL. 


Spacing 


$TEXT produces single spaced output. Macros for headings, tables, and figures 
cause appropriate spacing: between headings and text, between tables and 
text, and between figures and text. 


The user enters the TEXT control word .SPB between paragraphs. In certain 
cases, where a blank Line is needed but a page break is undesirable, the TEXT 
control word .SPF can be used. For example, .SPF should be entered in these 
cases: after a line ending in a colon that introduces a List of items on 
separate lines, between lines in a table where a page break is inappropriate, 
and between Lines in syntax formats. 


Section and Subsection Headings 


Documentation files are hierarchically structured. In addition to the section 
heading, four levels of headings are permitted. Headings created through 
macros are distinguished typographically (by upper- and lower-case and by 
underscoring) and by appropriate spacing. $TEXT also attaches specific 
meaning to the heading levels for hard-copy and HELP. 


When outlining a new manual, both the hard-copy heads and on-line HELP topics 
should be considered. For example, all commands of a given processor may 
appear as level 2 headings with Level 4 headings (such as "“Format:", 
"“Parameters:", etc.) subordinate to each command heading; the command names 
become topics, and "Format", "Parameters", etc. become subtopics for each 
command. The following discussion of level head macros illustrates this 
point. 


Note: In CP-6 user documentation, the order of level 4 heads for command (and 
similar) documentation is as follows: Format, Parameters, Description, 
Example. This order of presentation produces the most usable HELP facility. 
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Level O Head Macro 


Format: 


-»:LQH "section name" 


Parameters: 


section name is the 1-49 character section name. 


Description: 


This macro creates and formats the section name, and creates an entry in the 
table of contents (Cif it is requested at document assembly). 


Example: 
--:LOH "User Documentation/HELP" 


creates the section name for this section. 


Level 1-3 Head Macro 


Format: 


~-tL{1[2/33H "“"CheadnamelC;I({x|[ help topics Csynonym_list]}1" 


Parameters: 


headname is the heading name. headname can be up to 58 characters for 
Level 1, 55 for level 2, and 52 for level 3. 


help topic is the 1-31 character HELP topic name, if other than headname. 
help topic must be specified even if the same as headname if a synonym List 

follows. help _topics must not include blanks; for example, LEVEL_1 could be 
the topic associated with the heading "Level 1-3 Head Macro”. 


synonym List is a list of 1-31 character synonyms for the HELP topic. 
Synonyms must not contain blanks. 


Description: 
This macro creates and formats the level head, and creates an entry in the 


table of contents and index, if they are requested at document assembly. The 
macro also creates a HELP topic unless X is specified. 


Example: 
2e:L2H "COPY Command;COPY C CO COP" 


creates COPY Command as a hard-copy heading, COPY as a HELP topic, and C, CO, 
and COP as HELP synonyms. 
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Level 4 Head Macro 


Format: 


»-:L4H "Cheadnamel(;{xjhelp subtopic Csynonym lList]}1" 


Parameters: 

headname is the head contents of up to 255 characters. 

help subtopic is the 1-31 character HELP subtopic name, if other than 
headname. help subtopic must be specified, even if the same as headname, if a 


synonym List follows. help subtopic names must not include blanks. 


synonym_lList is a list of 1-31 character synonyms for the HELP subtopic. 
Synonyms must not include blanks. 


Description: 

This macro creates and formats the level 4 head (or table entry, if the Level 
4 head falls between ..:MAT and ..:END macros). If X is not specified, the 
macro creates a HELP subtopic, provided the preceding higher level head is a 
HELP topic. (Level 4 headings do not appear in the table of contents.) 


STEXT transforms Level 4 headnames, entered in metalanguage used to described 
syntax, into useable HELP subtopics. These transformations are described 
later in this section. 


Example: 
oe :L4H "Example:" 


creates a hard-copy heading and generates the HELP subtopic EXAMPLE. 


Usage Notes: 


1. If headname exceeds Line width in the output produced, headname is 


formatted on multiple Lines just as any other text, with Line breaks at 
blank characters. 
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Syntax Formats 


Two kinds of syntax formats are used: 
e COBOL-oriented syntax formats, used in COBOL, I-D-S/II and FPL documents. 
e General syntax formats, used in all other documents. 


Figure 7-1 is an example of a COBOL-oriented syntax format. 


OBJECT-COMPUTER CHIS-SERIES-60] LEVEL-66-ASCII 


C CWORDS +) 
C, MEMORY SIZE integer {CHARACTERS}] 
C {MODULES Be 


Calphabet-name}] 


CSTANDARD~-1 
{NATIVE 

7 PROGRAM COLLATING SEQUENCE IS {ASCII 
CEBCDIC 
{GBCD 
CHBCD 
{JIS 


AAAs mMm 


Figure 7-1. COBOL-oriented Syntax Format 


Notice the brace or bracket on each Line of a group, and the alignment of the 
braces and brackets that enclose the group. 


Figure 7-2 is an example of a general syntax format as it appears in a user 


document. Note that the OR bar is preferred to the vertical stacking of 
options. 


Syntax: 


PASSWORD {OLD=oldpasswordL,NEW=newpassword] |NEW=newpassword} 


Figure 7-2. General Syntax Format in a User Document 
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Tables 


Tables of seven Lines or more are appropriate to be formatted as named tables. 
ALL named tables are created through the use of macros. 


The table macro allows rapid entry of table text. The following List explains 
the three table types and when each is useful. 


e Matrix - tables consisting of rows and columns. Up to 8 columns of data 
are permitted. Each row of text is entered as one Line, with the # 
character as a column separator. Figure 7-3 shows a sample matrix table. 


e Formatted 2-column - tables consisting of a table item in the left column 
and formatted text in the right column. Each item in the first column, 
entered as a level 4 head, occupies a separate line in the table. Text 
explaining each item starts on a following Line Callowing a wide second 
column instead of one aligned beyond the longest item in the left column; 
this usually results in more compact tables). Each table item and 
accompanying text can be an individually selectable HELP subtopic. Figure 
7-4 shows a sample formatted 2-column table. 


e Unformatted - tables consisting of text in unformatted mode, i.e., the 


TEXT control word .FIF followed by text entered exactly as it is to appear 
in the output. Figure 7-5 shows a sample unformatted table. 


Table A-1. ASCII Character Codes 


0'oOO0' D'QOOO0' NULL of time fill character 
0'001' d'O01' Start Of Heading 

0'002' dD'O0e2' Start of Text 

0'003' D'003' End of Text 

0'004! dD'O004' End of Transmission 


Figure 7-3. Matrix Table 
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Table 1-2. Set Options 
Option Meaning 


ACCESS=((CALL|accountlist})C,controllist]) 


ALL is the control List is to apply to all 
other accounts. 


ACSVEH=(vehiclelist)C,controllist]) 


vehiclelist processors that are to be given 
access permissions. 
controllist one of the following permissions: 


DELRECORD 


Figure 7-4. Formatted 2-Column Table 


ee :MAT “Table 13-1. DBELTA Directives” 

-FIF 

-spf 2 

HOUSEKEEPING |EXECUTION [EXECUTION [MEMORY DISPLAY |MODE |MISC. 
| CONTROL | TRACING |& MODIFICATION [CONTROL| 


Input/Output Procedure HISTORY* Variable 
Control: Breakpoint:]| PLUGH* Oriented 

TRACE* Directives: 
COPY 


ee END 


Figure 7-5. Source for Unformatted Table 
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Purpose of :MAT Macro 


Table macros perform the following functions: 


e Insert and center the table title, including blank Line spacing. 
e Automatically create running titles for continuation pages. 
e Provide standard blank Line spacing to separate the table from preceding 


and following text. 
® Make logical page breaks. 


In addition, these functions are performed for matrix and formatted 2-column 
tables: 


e Insert and position column headings, including blank Line spacing. 
e Automatically create running headings for continuation pages. 
e Perform all the positioning for the columns. 


Before the table macros terminate, they always perform an .FIN, an .ALL and an 
-INL O so that the file builder is "reinitialized". 


ALl named tables included in a text source file are delimited by :MAT and :END 
macro calls as follows: 


oe:MAT “detail” 


table text 
ee END 


:-MAT Macro 


Format: 


oe tMAT “"titlelC;col headiC;CH#Iin;col_head2j]...J3" 


Parameters: 
title is the 1-61 character table title. 
col_head1 is the column heading for the first column. 


C#Iin;col_head2 specifies the position and column heading for the second 
column. If # is specified, n is relative to the end of the last column 
heading. If # is omitted, n is the absolute column position for the heading. 
For example, 35;Description causes the head to be placed in column 35. 
#5;Description causes the head to be placed 5 positions after the previous 
column heading. Matrix tables may consist of up to 8 columns; formatted 
2-column tables must have only 2 cotumn heads specified. 


Description: 
This macro labels and lays out a table consisting of the following text (Cup to 


the ..:END macro). It also includes the table name in the List of tables and 
figures in the table of contents (if a table of contents is requested). 
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Example: 


--:MAT "Table A-1. ASCII Character Codes;Graphic;#5;0ctal;#6; 
Decimal;#7;Hexadec.;#7;Definition"” 


is the macro used to create the matrix table in Figure 7-3. The first Line of 
source text in that table is entered in the source file as follows: 


NULL#AO'OOO'AD'OOO'HX'OO'HNULL of time fill character 


Following is the macro used to create the 2-column formatted table in Figure 
7-4: 


--:MAT “Table 1-2. Set Options;Option;15;Meaning" 


The first lines of source text in that table are entered in the source file as 
follows: 


2-:L4H "ACCESS=C(C(CALL|accountlist})Ccontrollist])" 
ALL”""*is the control List that is to apply to all other accounts. 


--:L4H "ACSVEH=(vehiclelist)C,controllistj)" 
vehiclelist”*"“"processors that are to be given access permission. 
-spb 0 
controllist”” 
-spf 0 
DELRECORD 


a 


“one of the following permissions: 


Note that the text between level 4 heads is indented (as requested in the :MAT 
macro) and formatted. 


Usage Notes: 
1. For matrix tables, text is left-justfied within the columns unless blanks 
are explicitly entered (by use of the up-arrow character). Adjacent pound 


signs are entered if a field in the matrix is to be left blank. 


2. For unformatted tables, no column headings are specified in the :MAT 
macro. Any column headings must be included with the table text. 


3. For matrix tables, the column headings and text (excluding # characters) 


cannot exceed 76 per line. For unformatted tables, each Line of table 
text is limited to 76 characters. 
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Figures 


Source text files should contain all artwork, not blank space for hand-drawn 
diagrams. (If desired, better quality artwork can overlay the artwork stored 
in the file if camera-ready master copies are being created.) 


ALL figures included in a source text file are delimited by the :FIG and :FND 
macro calls formatted as follows: 


o-:FIG "fig info" 


figure text 
ee FND 


:-FIG Macro 


Format: 


ee tFIG "titleC;n]" 


Parameters: 

title is the 1-61 character figure title. 

n is the estimated number of Lines in the actual figure. If n is not 

specified, $TEXT assumes the figure belongs on a single page. 

Description: 

This macro labels and lays out a figure consisting of the following text (Cup 

to the ..:FND macro). It also includes the figure name in the list of tables 

and figures in the table of contents Cif the table of contents is requested). 

S$TEXT uses the following rules to determine figure layout: 

1. If there is enough room on the current page, the figure is printed. 

2. If there is not enough room on the current page, and the figure is less 
than a single page in length, a break to the next page occurs and the 
figure is printed. 

3. If the figure is longer than a single page, the figure will begin printing 


on the current page, and all subsequent pages of the figure are printed 
with a figure title at the bottom of each page. 


Example: 
»e:FIG "Figure 7-3. Matrix Table;12" 


created Figure 7-3 in this section. 


Usage Notes: 


1. The figure content must be kept within 78 character positions, starting at 
character position 1. 


2. Areas in a figure can be forced to appear together by placing a .BRN above 
the area to be kept together. For example: 


-BRN 10 
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means the next 10 Lines must appear on the same page. Using an .SPF 0 is 
another way of forcing Lines in a figure to print on the same page. .SPF 
O specifies that this is an inappropriate place to break the current block 
of text. (Using .SPB 0 specifies that this is an appropriate place to 
break the current block of text.) 


3. Figures are created in .FIF mode and the .TRF is set so that the up-arrow 
prints. When the figure macro is exited, text is in .FIN mode, and the up 
arrow character is reset to the "blank replace" mode. 


Figure Symbols 


Figure 7-6 includes standard forms to be used in the construction of symbols 
used in electronically reproducible art. Some symbols can be represented in 
two ways: in an expanded or a condensed version. The expanded symbol uses 
dashes for top and bottom Lines instead of underscores. The expanded symbol 
is preferred because it allows space for more text within the figure. Within 
any figure, it is important to be consistent about the use of condensed versus 
expanded symbols. It is also recommended that consistency be maintained 
within sections and, if possible, within a document. 


Symbol Expanded Condensed 
Function Form Form 


Process (also qo maeae-aa----- 


annotation, comment, | | | | 


predefined process) | | | | 


Input/Output j= weeererneeen--- 
/ / a J 
/ / / / 
/ / / / 
Document (line i  aeweaneeenns--- 
printer, printer) | | yet aise 
| _/ | af 
| / / 
Manual operation seen nn--en---- 
\ / yo Se ee 
\ / \ / 
\ / \ / 
Preparation = se eess---- 
/ \ / \ 
< > < > 


nd 
~~ 
Prd 
om 


Figure 7-6. Figure Symbols (cont. next page) 
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Decision 


Connector 


Magnetic tape 


Display Calso TP 
terminal) 


Figure 7-6. Figure Symbols (cont. next page) 
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Auxiliary operation 


Punched card 


Online storage 


Direct arrows 


Communications arrows 


Figure 7-6. Figure Symbols 
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index Entries 


Indexes are created on request as part of document assembly. There is no 
Limit to the number of items that can be included in an index. The index for 
a manual consists of: 


e Automatic entries - all level 1, 2, and 3 heads contained in the document 
file. 

e Specified entries - entries selected by the user by entering the :IDX 
macro. 


IDX Macro 


Format: 


ee: IDX “termC;subtermj)" 


Parameters: 


term is the term to be entered into the index. 
subterm specifies that subterm is to appear in the index subordinate to 
term. 


Description: 


This macro creates an index entry. $TEXT, on request, produces an 
alphabetized, collated index. Upper and lowercase are considered identical; 
the first occurrence of a term will determine how an entry appears in the 
index. Thus, "ASDF" and “asdf" will be sorted together as "ASDF". Similarly 
"abcd" and "ABCD" will be sorted together as "abcd". 


Plurals and suffixes of a term are not combined with the original term. Thus 
"Process" and "Processing™ do not collate together. 
Example: 

~-:IDX "BUILD Command" 

ee:IDX "BUILD Command;EDIT" 

et IDX “BUILD Command; IBEX" 


creates a 2-level index, which could appear as follows for the terms shown 
above: 


BUILD Command - 2-10 
EDIT - 3-18 
IBEX - 4-20 

Usage Notes: 


1. The :IDX macro must follow the paragraph to which it refers. 


2. When a 2-level index is created by use of subterms, the term should be 
defined on one :IDX macro without subterms (Cas shown in the example). 
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Ending a Section 


All source text files must end with the following sequence: 


se cHLP "BRP" 
ee me 


This is the only time that the user is permitted to include a .BRP in a source 
text file. 


Preparing On-line (HELP) Documentation 


The CP-6 HELP facility is an on-line communication medium which provides quick 
information about processor capabilities. It is participatory in nature; that 
is, HELP issues messages in response to user requests for information. The 
HELP audience includes anyone who uses the CP-6 system from the novice to the 
experienced user. In addition to providing quick reference information, the 
HELP facility can be used for browsing. Through HELP browsing, the user can 
become familiar with the commands within a particular processor. 


Reference manuals, stored as properly structured source text files, can be 
used to produce both hard-copy manuals and on-line documentation. S$TEXT is 
designed to use level 1, 2, and 3 heads as HELP topics and level 4 heads as 
subtopics, unless otherwise directed. The task of encoding a source text file 
to also produce a HELP file is primarily a matter of suppressing topics that 
are inappropriate to HELP, supplying topic synonyms, and providing alternate 
wording for the on-line documentation (replacing references to other sections 
of the hard-copy document, for example). 


Encoding a Source File 


The HELP file creator uses encoding tools to transform a manual source file 
into a file containing a combination of manual information and HELP 
information. These tools enable the HELP processor to differentiate between 
material which is to appear in HELP and material which is to appear only in 
the manual. The semicolon (;) is the tool which allows HELP to make this 
distinction. 


A semicolon within a heading informs the HELP processor that anything to the 
Left of it is manual-only information and anything to the right of it is 
HELP-only information. Semicolons are always used when it is necessary to 
tell the HELP processor of one of the following conditions: 

e A level head and its text are to be excluded from HELP. 


e A HELP topic differs from the level head; also to supply synonyms for a 
HELP topic. 


e A HLP macro is entered to supply HELP~only text. 


“I 
j 
aah 
be] 
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Excluding Topics 


A HELP topic is automatically made of each level 1, 2 and 3 head unless steps 
are taken to exctude the head as a topic. HELP makes no distinction between 
levels 1, 2 and 3. Any level 1, 2 and 3 headings which are to be excluded 
from HELP must be specifically flagged. 


The following standard topics are good candidates for inclusion in HELP files: 
C) ALL statements, commands, verbs, and clauses. Their options with 
descriptions, syntaxes, syntax rules, usage notes and examples are 


subtopics. 


e Lists of reserved words, verb categories and compiler options. The 
description of each entry in the List is a candidate for a subtopic. 


e Miscellaneous subjects such as notation conventions. 


Good candidates for exclusion from HELP include: 


e Conceptual material 
e Tutorial information 
e References to Manuals, Sections, Tables and Figures 


For example, a level 1 heading INTRODUCTION and all text associated with it 
are not to be included in HELP. The HELP creator adds ;X to the heading to 
indicate that INTRODUCTION is not to be included in HELP. The heading then 
appears as: 


ee:L1H "“Introduction;x" 


The semicolon signifies that all information to the right of it is HELP-only 
material. The X signifies that the heading and subsequent text are excluded 
from HELP. The ;X is automatically turned off when the next level 1, 2 or 3 
head is encountered. If there are subsequent level 2 and 3 heads under 
INTRODUCTION which are to be excluded from HELP, they must also be flagged 
with a 3X. 


Topic Names and Synonyms 


A level 1, 2, or 3 head becomes a topic name by default. Any level 4 head 
subordinate to a level 1, 2, or 3 head included in HELP becomes a subtopic 
name by default. Alternate topics, subtopics, and synonyms can be provided by 
entering them to the right of the ;. 


If a single word appears on the right side of the ;, it is the topic name 
Cinstead of the heading name). If multiple values appear on the right side of 
the ; the first is the topic name and the subsequent values are synonyms. 

Each synonym is separated from the preceding value by a space. 


No single topic name, synonym or subtopic name may exceed 31 characters. The 
underscore is used as a connector (e.g., USAGE NOTES). 


Names 


Unless changed, the name of a topic (or subtopic) is the name of the heading. 
Topic names appear in the automatically generated HELP TOPICS message for a 
HELP file. It is important that the manual heading be examined to determine 
its appropriateness as a Listed item in the TOPIC tabular message. 
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Synonyms 


A synonym is an alternate name for a topic or subtopic. Synonyms are assigned 
in two cases: 


1. When a command (statement, etc.) can be abbreviated in one or more ways. 
2. When a concept can be named in more than one way. 
Note: Whenever a synonym is included, the topic (or subtopic) must always 
appear as the first word to the right of ; even if it is the same as the level 
head. 
Command Abbreviations 
For a good HELP file, each command that has abbreviations should be 
retrievable through any of its abbreviated forms. Messages are retrieved 
through that means. Therefore if a command is the topic, the HELP coding must 
include all valid abbreviations for the command. These abbreviations are 
introduced as name synonyms. 
The COPYALL command has the following syntax: 
CCOPYJACLLI 
The valid abbreviations for the COPYALL command are: 
CA,CAL,CALL,COA,COAL,COALL,COPA,COPAL,COPYALL,COPYA,COPYAL 
The HELP portions of the COPYALL heading must contain all of these 
combinations as synonyms for the user to be able to access the COPYALL topic 


using any one of the valid abbreviations. The heading appears as: 


--:L2H "COPYALL Command;COPYALL CA CAL CALL COA COAL COALL 
COPA COPYA COPYAL" 


Notice that the List begins with the full command form "COPYALL". The full 
command form is always listed first because only the first form will be listed 
in the HELP TOPICS message. 
Conceptual Synonyms 
Conceptual synonyms give the user a choice of ways to access a topic which may 
have several different names. For example, suppose a portion of text 
appearing under the heading "Possible Error Conditions" is to be included in 
the HELP file. The heading appears in the manual as: 

eetlL1H "Possible Error Conditions" 
One user may think of the word “errors" while another user may think of the 
words "warnings" or "problems". Using synonyms, the HELP creator can assign 


all three names to the topic. The heading is changed to appear as: 


»~-:L1H "Possible Error Conditions; ERRORS WARNINGS PROBLEMS" 
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Encoding Subtopics 


A subtopic is the name of a retrievable submessage associated with a HELP 
topic. Entering the HELP request for a command followed by a subtopic 
produces only the subtopic information. 


Consistent organization and presentation of material is critical for 
successful use of subtopics. Messages in one subtopic must be the same 
structure as similar messages in other subtopics. 


The HELP file creator must determine: 


@ If any subtopics need to be excluded or modified. 
e Appropriate subtopic names and synonyms. 
e What table entries to include as subtopics. 


Creating Subtopics 


Any Level 4 head appearing under a higher level head that is a HELP topic is 
automatically a subtopic. Any level 4 head appearing under a higher Level 
head that is not a HELP topic is automatically excluded from HELP. To create 
a subtopic for a subject appearing at a level 2 or 3 head requires the 
insertion of a level 4 head of HELP-only information. For example, suppose 
LITERALS appears in the manual file as: 


ee:L2H "Literals" 
; text 

--:L3H “Nonnumeric Literals" 
. text 

eet SH “Numeric Literals" 


- text 


The HELP creator wants to make NONNUMERIC and NUMERIC subtopics of LITERALS. 
The manual file is modified to appear as: 


ee-:L2H "Literals" 

- text 
--:L3H "“Nonnumeric Literals;" 
-»-2:L4H "“;NONNUMERIC"™ 


- text 


-e-:L3H “Numeric Literals;" 
»e:L4H ";NUMERIC"™ 


- text 
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The topic LITERALS now has the subtopics NONNUMERIC and NUMERIC. Adding the 
semicolon at the Level 3 head prevents those headings from becoming topics in 
themselves while preserving the text under them for the HELP file. Adding the 
level 4 head with the semicolon in front of the heading contents creates a 
HELP subtopic name which does not appear in the manual but does appear in 
HELP. 


Subtopics Within Tables 


Named subtopics are useful also for direct access to items such as compiler 
options. In a table of compiler options, each option is a level 4 heading. 
The named topic, in this case the name COMP_OPTIONS, is a level 1, 2 or 3 
heading (i.e., .«.:L1H ";COMP_OPTIONS" is specified immediately following the 
=MAT macro). 


Entering only the named topic produces a List of all the options in the table. 
For example, to obtain a List of all compiler options for PL6, the user 
enters: 


HELP (PL6) COMP_OPTIONS 


A List of all the compiler options in PL6 is produced. The user decides to 
view only the NFORMAT option for the PL6 compiler and enters: 


HELP (PL6) COMP_OPTIONS NFORMAT 


The syntax for the NFORMAT option appears along with a brief description of 
the option's function. 


Automatic Transformation of Subtopics 


The HELP processor examines each character in the heading separately to 
transform the manual entries to HELP subtopics. In the above example, NFORMAT 
actually appears in the manual as NFORCMAT]. Braces and brackets are removed 
from the heading. Any OR bars ("|") are transformed into blank spaces and 
anything following a "(", "ss", "3", "=" or " " is deleted from HELP. Whatever 
remains is converted to uppercase. Table 7-3 illustrates the conversion from 
the source file to the HELP file. 
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Table 7-3. Examples of :L4H Transformation 


Heading Converted Subtopic Name 


"ABCCDE]" ABCDE 


"{CAB{CD}" AB CD 


"CABCC]|DE}" ABC DE 


"ABC=n" ABC 
2e:L4H "ABC: DE" ABC 


2 :l4H “Example:" EXAMPLE 


:HLP Macro 


Format: 


ee tHLP "Cmanual_textiCrhelp_text]" 


Parameters: 


manual_text is text that is to appear in the manual, but not in the HELP 
file. 

help text is text that is to appear in the HELP file, but not in the 
manual. 


Description: 


This macro allows entry of alternate wording for the hard-copy manual and for 
the HELP file. 


Example: 
ee :HLP "Refer to Section 3 of this manual for details;" 


is text for the manual only, since references to Section 3 are inappropriate 
for the user of the HELP file. 


e-e-:HLP ";HELP messages for each option can be obtained” 
2etHLP ";by entering HELP (PL6) COMP_OPTIONS option" 


is text for the HELP file only since references to HELP topics are 
inappropriate for the manual. 


o-tHLP "See Table 2-2 for a list of compiler options;Enter 
HELP COMP_OPTIONS for a List of compiler options" 


provides alternate wording for the manual and the HELP file. The example is 
functionally identical to: 


«--:HLP "See Table 2-2 for a List of compiler options;" 
2-:HLP "ZEnter HELP COMP_OPTIONS for a list of compiler options” 
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Creating a HELP File 


The HELP file is built through STEXT. The HELP file creator invokes $TEXT a 
directs the output of processing to a file. S$TEXT in turn, invokes the X 
account program HERMAN which creates the HELP file. 
The following dialog illustrates how a HELP file can be generated from one 
source file. 
Prompt Action 
'XEQ STEXT.:DOCUM Call the document assembly 
program. 
FASTEXT B03 
Files to Format>CE29 01 Enter the file name. 
In account>:MANUALS Enter the account the manual 
files are in. 
Device or Destination>Z0O COBOL1_ HELP Enter the name of the file to 
be created, ZO COBOL1 HELP. If 
that exists, a prompt is issued 
asking if you want to write 
over it; respond with a "Y". 
By convention, this file name 
is of the form 
fcg_ processorname HELP, where 
fcg is the Functional Code 
Group (FCG). The “COBOL1” 
portion of the file name 
indicates the manual Section 
(1) for a HELP section file. 
TEXT OPTIONS> Enter a carriage return <CR>. 
DRAFT or FINAL Format>H Enter H for HELP. 
Pagesize (type of paper) Enter a <CR>. 
Number of Copies > Enter a <CR>. 
Extra Files >I Enter an I to get a HELP index. 
Do you want these files for :MANUALS: 
ORG TY GRAN NGAV REC LAST MODIFIED NAME 
KEY oe 0 541 11:50 NOV 23 '81 CE29 01 
creating HELP source file named ZO COBOL1 HELP 
creating a readable HELP file named HELP:COBOL1: 
Enter Y to send the job, C to reenter the values, or <CR> to exit. 
Go for it?>Y Enter a Y to create a HELP file. 
Once HELP files for several sections have been created and tested, the HELP 
file creator can invoke $TEXT in document assembly mode specifying multiple 
section files to produce a single HELP file. 
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Section 8 


Techniques: Central System 


This section discusses a number of interfaces to central system software and 
includes sample code. 


Accessing the JIT 


The Job Information Table (JIT) contains system related information about an 
individual CP-6 user. From logon to logoff time, the JIT accumulates and 
retains facts about a user's session. The information contained in the JIT is 
useful for programmers writing programs to run on the CP-6 system. 


The JIT is the area in memory that gathers and records specific facts about 
the user such as the users's account, mode, name, sysid and accounting 
information. 


The JIT is accessed in several different ways; via the Linker-built pointer 
BSJIT$, the JIT can be examined through DELTA by using Linkage segment number 
one ($LS1) or by using $JIT. Any command processor automatically has 
modification access to the JIT. A run unit that resides in the :SYS account 
and that has been Linked with JIT alteration privilege also has modification 
access to the JIT. Appendix A include a description JIT fields and a DRAW of 
the structure. Figure 8-1 illustrates a PL-6 subroutine which returns a 
user's Logon account and user name from the JIT to a FORTRAN program. 
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Ve JIT MAIN SIF 
PROGRAM JIT 
CHARACTER * 8 MYACCT 
CHARACTER * 12 MYUNAME 
CALL GETJIT (CMYACCT,MYUNAME) 
WRITE (108,1000) MYACCT, MYUNAME 
1000 FORMAT (1X,A8,1X,A12) 
STOP 
END 
Ic JIT_SUB_SI6 
/*M*x Subroutine returns logon account and 
user name from JIT to FORTRAN program */ 


GETJIT: PROC CACCT, UNAME); 


DCL ACCT CHAR(8); 
DCL UNAME CHAR(12); 


DCL BSJITS PTR SYMREF; 

NINCLUDE BSJIT; 

ACCT = BSJITS -> BSJIT.ACCN; 

UNAME = BSJIT$ -> BSJIT.UNAME; 
RETURN; 

END GETJIT; 

! FORTRAN JIT MAIN SIF OVER *G(NLS) 
FORTRAN 77 VERSION BOS AUG 20 '82 


'PL6 JIT SUB _SI6 INTO *GC(SRC.:LIBRARY),NLS) 
PL6 BO2 here at 15:32 AUG 20 '82 


No errors detected in file JIT_SUB SI6 


'LINK *G OVER #*L 

*  :SHARED COMMON.:SYS (Shared Library) associated. 
* No linking errors. 

* Total program size = 

Yel 


XWKPL6 876KWIK 
*STOP* 


Figure 8-1. Accessing the JIT Using PL-6 Subroutine 
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Accessing the Task Control Block (TCB) 


The Task Control Block (TCB) contains system related information about a 


running 


program. From fetch to rundown time, the TCB accumulates and retains 


facts about a user's program including information about monitor service 
ALTRETURNS, interrupts, faults and asynchronous events. 


The TCB 
BSTCBS$, 
fifteen 
related 
section 


Figure 8-2 shows a PL-6 subroutine which accesses the TCB, 


service 


is accessed in several different ways; via the Linker-built pointer 
the TCB can be examined through DELTA by using Linkage segment number 
($LS15) or by using $TCB. The Layout of the TCB and the structures 
to it are described in the Monitor Services Reference Manual, in the 
on Exception Condition Services. 


error code from the altreturn frame. 


returning a monitor 


i 


1C ERR SI6 


/xM*x Get error code from TCB, print using MSERRMSG */ 
ERRMSG: PROC MAIN; 
“ZINCLUDE cP_6; 
“INCLUDE CP 6 SUBS; 
DCL M$DO DCB; 
DCL MY ERROR BUF CHAR(255) STATIC; 
DCL BSTCBS PTR SYMREF; 
%FPT ERRMSG CFPTN=ERROR_ PRINT, 
BUF=MY_ERROR BUF, 
OUTDCB1=M$D0, 
CODE=NIL); 
XBSTCB; 
ZBSALT; 


ERROR PRINT.CODE = VECTOR(BSTCBS->BSTCB.ALT$->BSALT.ERR); 


CALL MSERRMSG CERROR PRINT) ALTRET CHMMM) ; 


HMMM: CALL MS$XXX; 

END ERRMSG; 

!PL6 ERR S16 OVER *GC(NLS,SR(.:LIBRARY) ) 
PL6 BO2 here at 14:01 SEP O2 ‘82 


No errors detected in file ERR SI6 


'RUN *G 


*  :SHARED SYSTEM.:SYS (Shared Library) associated. 


* No Linking errors. 
* Total program size = 3K. 


MMP-M00606-0 Attempt to free more space than is 


MSXXX issued by user. 


Note: MMP-~M00606-0 is the error given to 


Figure 8-2. Accessing the TCB Using PL-6 Subroutine 
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in data segment. 


:SHARED SYSTEM when 
the memory in AUTO prior to starting a PL-6 MAIN program. 


it releases all 


Break Handling 


Break handling allows a time sharing user to hit the break key while a program 
is running and either check on the program's progress, or provide for an 
alternate routine or exit. To create a break handling routine, a user must 
provide a PL-6 subroutine which calls the M$INT Monitor Service to establish 
and setup an address for the break handler. The break handler subroutine must 
be a PL-6 asynchronous procedure (PROC ASYNC). Figure 8-3 shows a FORTRAN 
program with a PL-6 subroutine that handles a break by clearing the break 
frame from the Task Control Block (via the call to MS$CLRSTK) and forcing the 
program to exit on a special path. Note the call to the MSTRMPRG monitor 
service which is included to avoid four breaks simulating CONTROL~Y; see the 
discussion of M$TRMPRG in the CP-6 Monitor Service Reference Manual for 
details. 


!c INT SIF 
PROGRAM INT 
CALL SETUPINT(110S) 
DO 100 1=1,10 
CALL SLEEP(10) 
OUTPUT I 
CONTINUE 
OUTPUT ‘ALL DONE! 
CALL EXIT(O) 
OUTPUT 'BACK FROM BREAK’ 
STOP 
END 
SUBROUTINE BREAKH(*) 
OUTPUT ‘IN FORTRAN BREAK ROUTINE! 
RETURN 1 
END 
!C INT_SI6 
/*M* INT HANDLERS FOR EXAMPLE PROGRAM */ 
SETUPINT: PROC (ENTPOINT); 
DCL ENTPOINT PTR; 
DCL INTPTR PTR STATIC SYMDEF; 
“MINCLUDE CP 6; 


DCL MY_ INT ENTRY ASYNC; 


%FPT_INT CFPTN=MY_INT_FPT,UENTRY=MY_INT); 


INTPTR = ENTPOINT; 
CALL MSINT C(MY_INT_FPT) WHENALTRETURN DO; 
RETURN; 
END SETUPINT; 
%EOD; 
MY_INT: PROC ASYNC; 
DCL INTPTR PTR SYMREF; 
DCL BREAKH ENTRY (1); 
XINCLUDE CP 6; 
XFPT_TRMPRG (DCB=M$UC,RSTBRK=YES); 


CALL MSCLRSTK; 
CALL MSTRMPRG C(FPT_TRMPRG) WHENALTRETURN DO; END; 
CALL BREAKH CINTPTR); 


RETURN; 
END MY_INT; 
%EOD; 
SLEEP: PROC (TIME); 
“INCLUDE CP_6; 
%FPT WAIT (CFPTN=ZZZZZ); 
DCL TIME SBIN; 


Figure 8-3. Break Handling Via PL-6 ASYNC Procedure (cont. next page) 
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ZZZZZ.V.UNITS#=TIME; 

CALL MSWAIT (22222); 

RETURN; 
END SLEEP; 
!'FORTRAN INT SIF OVER *GCNLS) 
FORTRAN 77 VERSION COO NOV Q3 '83 
'PL6 INT _SI6 INTO *GC(NLS,SRC.: LIBRARY) ) 
PL6 BO2 here at 15:56 NOV 03 '83 

No diagnostics issued in procedure SETUPINT 


No diagnostics issued in procedure MY_INT 


No errors detected in file INT_SI6. 


'LINK *G OVER #*L 

* :SHARED_COMMON.:SYS (Shared Library) associated. 
* No Linking errors. 

* Total program size = 3K. 

Pee 


I=1 
I = 2 
IN FORTRAN BREAK ROUTINE 
BACK FROM BREAK 
*STOP* 


Figure 8-3. Break Handling Via PL-6 ASYNC Procedure 


Trap Handling 


Trap control allows the user to gain control in the case of a hardware 
detected fault (trap). Trap handling allows the user to detect and 
accommodate fault conditions. Trap control is usually taken by highly 
generalized, widely used libraries of utility subroutines. To create a trap 
handling routine, a user must provide a PL-6 subroutine which calls the MSTRAP 
Monitor Service to establish and set-up an address for the trap handler. The 
trap handling routine must be a PL-6 asynchronous procedure (PROC ASYNC). See 
the Monitor Services Reference Manual for a complete description of MSTRAP. 
Figure 8-4 shows a FORTRAN program with a PL-6 subroutine that handles a trap 
by clearing the trap frame from the Task Control Block (via a call to 
MSCLRSTK) and forcing the program to exit on a special path. 


! FORTRAN TRAP_SIF OVER *FC(LS,0U) 

FORTRAN 77 VERSION BO4 SEP 20 ‘82 

* 1.000> : PROGRAM TRAP 
2.000> CALL SETTRAP(100S) 
3.000> OUTPUT ‘GOING TO DIVIDE BY ZERO’ 
4.000> CALL DIVIDE(4,0,RESULT) 
5.000> OUTPUT ‘BACK FROM SUBROUTINE' 
6.000> STOP 'ME BEFORE I KILL AGAIN 
7.000> OUTPUT 'GOT A ZERO DIVIDE’ 
8.000> STOP 
9.000> END 

ERRORS FOUND : TOTAL ERRORS FOUND: O 


OONAULEWN = 


10.000> : SUBROUTINE DIVIDE (DIVIDEN,DIVISOR,QUOTI) 
11.000> : QUOTI=DIVIDEN/DIVISOR 
12.000> RETURN 
13.000> : END 
ERRORS FOUND : TOTAL ERRORS FOUND: O 


Figure 8-4. Trap Handling Via a PL-6 Subroutine (cont. next page) 
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14.000> ye SUBROUTINE ZERODIV (*) 

15.000> 2: OUTPUT ‘WHOOPS! ZERO DIVISION ENCOUNTERED' 
16.000> 3% RETURN 1 

17.000> 4: END 


ERRORS FOUND 0 


TOTAL ERRORS FOUND: O 


'PL6 TRAP_SI6 OVER *6(LS,0U,SRC.:LIBRARY) ) 
PL6 BO2 here at 15:55 SEP 20 '82 


1.000 1 /*M* SET UP TRAP CONTROL */ 

2.000 2 SETTRAP: PROC (LABEL); 

3.000 3 

4.000 4 “INCLUDE CP 6; 

5.000 81 1 DCL LABEL PTR; 

5.100 82 1 DCL MY_LABEL PTR STATIC SYMDEF; 

6.000 83 1 DCL MY TRAP ENTRY ASYNC; 

7.000 84 

7.010 85 %FPT TRAP (FPTN=SETUP_TRAP, 

7.020 86 ARITHMETIC=MY_TRAP, 
7.030 87 DIVIDE CHECK=TRAP); 
7.040 110 

7.050 111 2 CALL MSTRAP (SETUP_TRAP) WHENALTRETURN DO; END; 
7.055 112 1 MY LABEL=LABEL; 


7.060 113 

7.070 114 1 RETURN; 
7.080 115 

7.090 116 1 END SETTRAP; 
8.000 117 ZEOD; 


No diagnostics issued in procedure SETTRAP 


9.000 1 MY TRAP: PROC ASYNC NOAUTO; 
10.000 2 

11.000 3 1 DCL ZERODIV ENTRY(1); 
12.000 4 1 DCL MY LABEL PTR SYMREF; 
13.000 5 

14.000 6 ZINCLUDE CP_6; 

15.000 83 

16.000 84 1 CALL MSCLRSTK; 
17.000 85 

18.000 86 1 CALL ZERODIV (MY LABEL); 
19.000 87 = 
20.000 88 1 RETURN; 

21.000 89 1 END MY_ TRAP; 


No diagnostics issued in procedure MY_ TRAP 


No errors detected in file TRAP_SI6 


'LINK *F,*6 OVER *L 
* :SHARED_COMMON.:SYS (Shared Library) associated. 
* No Linking errors. 

* Total program size = 3K. 

Pee 


GOING TO DIVIDE BY ZERO 
WHOOPS! ZERO DIVISION ENCOUNTERED 
GOT A ZERO DIVIDE 

*STOPs 


Figure 8-4. Trap Handling Via a PL~6 Subroutine 
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Associating or Linking to Another Program a 


Associating another program with a currently running program can be 
accomplished by one of three monitor services: 


e MSLINK passes control to another program which runs and then returns 
control to the original program following the call to MSLINK. 


e MSLDTRC passes control to another program; context from the original 
program is not saved. 


e MSALIB passes control to a shared Library, an alternate shared library, or 
a debugger. 


The uses for M$LINK and MS$LDTRC are straightforward. One point illustrated in 
Figure 8-5 is particularly important to note: setting of the command Line 
DCBs (#1, #2, #3, #4) for a newly associated program can be performed by a 
call to the M$YC monitor service. Figure 8-5 illustrates how this is done in 
a PL-6 subroutine (which may be called within a FORTRAN program, for example). 
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DRIBBLE ON a 
'B *2 
EDIT BOS HERE 
1.000 THIS IS A TEST. 
2.000 IT IS ONLY A TEST. 
3.000 
'C *2 OVER *1 
--COPYing 
!C LINK S16 
/*M*x LINK_TEST «/ 
/*X* DMR,PLM=5,IND=3,CTI=3,SDI=3,MCL=10,CSI=0,ECI=0 */ 
LINK TEST:PROC MAIN; 


13:41 01/12/83 


XINCLUDE CP_6; 
%INCLUDE CP_6 SUBS; 


XFPT_YC 


(FPTN=SET 1, 
CMD=SET_1_ CMD, 
NOERR=YES); 


%FPT_LINK (FPTN=LINK_ TUNA, 
CMD=TUNA_CMD, 
NAME=TUNA_NAME, 
ACCT=TUNA ACCT); 
DCL 1 TUNA_CMD STATIC, 
2 * UBIN BYTE CALIGNED INITC(SIZECC('TUNA.X (LEN=79)')), 
2 * CHAR(O)  CALIGNED INITC'TUNA.X (LEN=79)'); 
XVLP_NAME (FPTN=TUNA_NAME, 
NAME='TUNA'); 
XVLP_ACCT (FPTN=TUNA ACCT, 
ACCT="X i 


DCL SET _1_CMD CHAR(O) STATIC INITC'!ISET #1 *1'); 


CALL MSYCCSET 1) 
WHENALTRETURN 
DO; 


CALL MSXXX; 
END; 


CALL MSLINK .CLINK_ TUNA) 
WHENALTRETURN 
DO; 


CALL MSXXX; 
END; 


CALL MSEXIT; 


END LINK_TEST; 
'PL6 LINK SI6 OVER *G(NLS) 

PL6 BO2 here at 13:41 JAN 12 '83 

No errors detected in file LINK_SI6. 


'LINK *G OVER *L 
* sSHARED SYSTEM.:SYS (Shared Library) associated. 
* No Linking errors. 

* Total program size = 3K. 

Pel 

1c *1 

THIS IS A TEST. IT IS ONLY A TEST. 

'DONT DRIBBLE 

DRIBBLE OFF @ 13:42 01/12/83 


Figure 8-5. ODCBs for Program Called by M$LINK/MSLDTRC 
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MS$ALIB is typically used in cases such as these: 
e To dynamically change the shared Library in use. 


e To dynamically associate an Alternate Shared Library, such as I-D-S/II, 
based on need rather than automatically associating the data base manager 
at invocation of a program. 


® To dynamically associate a debugger to diagnose an error condition. 


The sample subroutine shown in Figure 8-6 associates the CP-6 debugger, DELTA, 
to ascertain the Location at which an error occurred. This example shows how 
to obtain the Instruction Counter (from the TCB) for the error location and 
return it for display by the erring program. 
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!C ALIB SI6 


/*X* DMR,PLM=5,IND=3,CTI=3,SDI=3,MCL=10,CSI=0,ECI=0 */ 
ALIB TEST: PROC MAIN; 


DCL SETXCON ENTRY; 


DCL PTRS PTR STATIC INITCADDRCARRAY)); 
DCL ARRAY(0:1024) SBIN STATIC; 
DCL WORD  SBIN BASED(PTRS); 
DCL X_ SBIN WORD; 


CALL SETXCON; /* SETUP THE XCON ADDRESS */ 


DO WHILE('1'B); /* I KNOW THIS CODE DOESN'T WORK */ 


/* I WANT TO FORCE A FAULT SO */ 
PTRS=PINCRW(PTR$,-1); /* MY XCON ROUTINE WILL BE */ 
X_ = PTR$S->WORD ; /* ENTERED */ 
END; /* DO FOREVER */ 


END ALIB_TEST; 
%E00; 
SETXCON: PROC; 
DCL MY XCON ENTRY ASYNC; 
ZINCLUDE CP 6; 

“FPT_XCON CFPTN=SET_XCON, 
UENTRY=MY_ XCON); 


CALL MSXCON CSET_XCON) 
WHENALTRETURN 

DO; 
END; 


RETURN; 
END SETXCON; 
ZE0OD; 
MY XCON: PROC ASYNC; 
XINCLUDE CP_6; 


%FPT_XCON (FPTN=RESET XCON); 


XFPT_ALIB (FPTN=PRINT ADDRESS, 
CMD=DELTA_CMD.NAME#, 
ECHO=YES, 
DLIB=YES, 
LIBNAME=DELTA_NAME, 
RETRN=YES); 


SVLP_NAMECFPTN=DELTA_CMD, 
NAME="EVAL .O00000\R'); 


SVLP_NAMECFPTN=DELTA_NAME, 
NAME="DELTA'); 


%FPT_ERRMSG CFPTN=MY_ ERROR, 
BUF=ERROR BUF, 


OUTDCB1=M$D0); 


DCL BSTCBS PTR SYMREF; 


/* BASED STRUCTURES TO 


LOOK AT TCB */ 


*BSTCB; 
%4BSXCON; 
~ABSEXCFR; 


Figure 8-6. Associating DELTA to Dump I.C. (cont. next page) 
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or Linking to Another Program 


DCL I SBIN; 
DCL J SBIN; 
DCL 1 X(0:5), 

2 Z_ UBIN(3) UNAL; 
DCL X REDEF X UBIN(18) UNAL; 
DCL ERROR BUF CHAR(140) STATIC; 
MS$DO DCB; 


/* PRINT ERROR MESSAGE THAT 
CORRESPONDS TO ERROR CODE 
IN XCON FRAME ON TCB */ 


MY ERROR.CODE = VECTOR(BSTCB$->BSTCB.STKS->BSXCON.ERR); 


CALL MSERRMSGCMY_ ERROR) 


WHENALTRETURN 
DO; 
END; 
/* GET IC FROM TCB FRAME */ 
X_ = BSTCBS->BSTCB.STKS->BSEXCFR.IC; 


/x CONVERT IC TO PRINTABLE 
FORM SO IT CAN BE PASSED 
TO DELTA */ 


J=6; 
DO I = 0 TO 5; 


CALL INSERT (DELTA_CMD.NAME#,J,1,BINASCC(X.Z (€1)+48)); 
J=J+1;3 


END; /* DO I=0 TO 5 */ 


/* GO ASK DELTA TO EVALUATE 


THE IC */ 
CALL MSALIB (PRINT_ADDRESS) 


WHENALTRETURN 
DO; 
END; 


CALL MS$XCON CRESET_XCON) 
WHENALTRETURN 
DO; 

END; 


CALL MSEXIT; 
END MY_XCON; 
'PL6 ALIB_ SI6 OVER *G 
PL6 BO2 here at 13:00 JAN 12 '83 

No errors detected in file ALIB SI6. 


'LINK *G OVER *L 
* sSHARED SYSTEM.:SYS (Shared Library) associated. 
* No Linking errors. 
* Total program size = 4K. 
Pee 
HFA-M00520-6 Missing Page fault 
S$ALIB >EVAL .004017\R 


= ALIB_ TEST :16,,.1 CASSIGNMENT] 
!DONT DRIBBLE 


DRIBBLE OFF @ 13:01 01/12/83 


Figure 8-6. Associating DELTA to Dump I.C. 
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Shared Data Segments 


Data segments may be shared by separate programs that run independently or by 
programs which call one another via the M$LINK monitor service. The two types 
of data segment sharing are discussed below. 


Sharing COMMON between M$LINKed Programs 


Programs that call one another via the M$LINK monitor service may pass data in 
the COMMON data segment, i.e., data segment 2. To allocate the COMMON data 
segment, the M$GDS monitor service can be called with SEGSIZE set; this 
returns (via the RESULTS area) a vector framing the COMMON data segment. Once 
the data segment is allocated, M$GDS (with SEGSIZE=0) simply returns a vector 
framing the segment. 


Sharing Data Segment between Independent Programs 


Programs that have a need to share up to 256K of data may use a shared data 
segement to provide fast access to that data. By using the MSOPEN monitor 
service, the programs may establish or access a shared data segment. The 
programs can access the data in the shared data segment without performing 
physical I/0 for each access. Parameters that must be specified on the call 
to MSOPEN are as follows: DCB, NAME, ACCT, FUN which are set as appropriate 
and ORG=RANDOM, ACS=DSn, and ASN=FILE. The file will be opened and mapped 
into the specified data segment. 


To access the data segment, the programs use either the SYMREFed pointer 
BSDSn$S$ or the M$GDS monitor service called specifying SEGSIZE=0 and RESULTS= a 
VLP_VECTOR structure. The VLP_VECTOR.SEGID field should be filled in with 
%DSnSID from the B_SEGIDS C include file. The call to M$GDS returns a vector 
CVLP_VECTOR) framing the data segment. 


The MSCLOSE and MSEXTEND monitor services may also be used to manipulate a 
shared data segment. 


Programs that share a data segment in this way must take complete 
responsibility for assuring the integrity of the data. Such programs need to 
include Locking mechanisms for this purpose (e.g., M$ENQ to assure that the 
item or group of items it accesses contains current information and that no 
updates are Lost). 
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Virtual Data Segments 


A virtual data segment is much Like any other CP-6 data segment: it is an 
addressable portion of memory which may be used to store and access user data. 
Virtual data segments differ from standard data segments in several ways: 


) A virtual data segment may be much Larger than a standard data segment. 
Virtual data segments may contain up to 4 gigawords (4,294,967,296) of 
data each; the user is permitted to have up to 3 virtual data segments in 


existence at any particular time, yielding a total of 12 gigawords of 
address space. 


e As their name implies, virtual data segments reside in memory in a virtual 
sense, and not necessarily in areal sense. Since the size of a virtual 
data segment may easily exceed the memory-usage authorization of the user 
Cand may actually exceed the total amount of real memory available on the 
entire CP-6 system), only a portion of each virtual data segment actually 
exists in real memory at any particular time. The CP-6 hardware and 
monitor conceal this fact from the user's program, by bringing selected 
portions of the virtual segments into "real" existence whenever they are 
needed by the program. 


e Virtual data segments can “survive” after the program which created them 
has ceased to exist. Each virtual segment is associated with a CP-6 keyed 
file, stored on disk; this file is identified by the user's program when 
the virtual segment is initialized, and may be cataloged, stored, backed 
up, and deleted in the same way that any CP-6 file is manipulated. If a 
virtual data segment's file is closed and cataloged in a file directory, 
another program may subsequently re-open the same file and access its 
contents as a virtual segment; the data stored in the original segment is 
available, intact, in the new segment. 


e Special addressing techniques are necessary to access the contents of the 
virtual segment, if its total size exceeds 256K words. 


How Virtual Segments Work 


A virtual data segment is actually a way of addressing data which exists in a 
CP-6 keyed disk file. Virtual data segments are initially created by use of 
the MSOPEN service and are released by use of the MSCLOSE service; they are 
subject to all normal CP-6 file creation and access rules. To create a 
virtual segment (and its associated disk file), the user's program must issue 
an MSOPEN which includes a special VIRTUAL option (specifying a particular 
VLP VIRTUAL data structure). The program must supply the following 
information: 


1. The identity of a DCB which is to be used to store this virtual segment. 
The DCB must be assigned to an ASN=FILE, ORG=KEYED file (with a 
DISPosition of either NAMED or SCRATCH). The OCB may be opened with 
FUN=CREATE,EXIST=NEWFILE to create a new segment, or with FUN=UPDATE to 
access an existing virtual-segment file. 


2. The virtual size of the segment (i.e., the amount of space that the user 
wishes to be able to access). This value is specified as a decimal number 
of words, and is passed through the SEGSIZE option of the VLP_VIRTUAL 
structure. 


3. The physical size of the segment (i.e., the amount of real memory which is 
to be used to retain portions of the virtual data). This value is 
specified as a decimal number of pages (not words), and is passed through 
the PHYSICAL option of the VLP_VIRTUAL structure. 
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The CP-6 monitor opens the indicated DCB as specified. The user may then 
examine the field VLP_VIRTUAL.PTRS$, which contains a pointer to the base 
(beginning) of the newly-created virtual segment in memory. 


The user's program may now use the virtual data segment as it would use any 
other CP-6 data segment (subject to the addressing Limitations discussed 
below). The program may store or access data at any location within the 
segment's virtual address Limits. If the program attempts to access a portion 
of the virtual segment which does not currently reside in real memory, the 
following sequence of events occur: 


1. The CP-6 hardware's memory-management logic generates a "missing page” 
fault. 


2. The CP-6 monitor's trap handler determines that the fault occurred while 
accessing a virtual data segment, and calls the virtual-segment manager. 


3. The virtual-segment manager Looks through the real pages currently 
assigned to the virtual segment, trying to find one or more pages which 
have not been accessed recently. The pages which have not been accessed 
for the greatest Length of time are selected for purging. 


4. The virtual-segment manager purges the oldest Little-used page, by writing 
it into the keyed file associated with this segment if the page has been 
modified recently. (If the page has not been updated since it was last 
MSREAD from the keyed file, it is not re-written). 


5. The virtual-segment manager issues an M$READ, to bring the virtual page 
needed by the program into the physical page just purged. The user's 
memory map is updated to reflect the change in real memory allocation. 


6. The CP-6 monitor returns control to the user's program. The instruction 
which triggered the "missing page" fault is re-executed, and normally runs 
to completion. 


Note: The virtual-segment manager brings pages into real memory strictly 
on an "as-needed" basis, and only moves one page at atime. Thus, if an 
instruction accesses several pages in a virtual data segment, it may 
generate more than one "missing page" fault; the virtual-segment manager 
is called once for each fault, and brings in one page each time. 


A special case of this sequence occurs during the initial use of a virtual 
data segment, when few virtual pages have ever been accessed. If a "missing 
page" fault occurs, and the virtual data segment does not yet have as many 
real pages allocated as are permitted, then the virtual-segment handler simply 
allocates a new real page to hold the as-yet-unused virtual page, and it 
returns control to the user's program without performing any disk I/0 
operations. Thus, if the user's program actually allocates enough real pages 
to hold that portion of a virtual segment that it really accesses, then Little 
or no disk I/0 is necessary. 


A virtual data segment (and its associated disk file) is released by use of 
the standard monitor service M$CLOSE. The program may opt to retain the 
segment file, or to discard it, as follows: 


e If the MSOPEN which created the segment specified DISP=SCRATCH, or if the 
MSCLOSE which releases it specifies DISP=RELEASE, then the segment and its 
associated disk file are immediately discarded. The information stored in 
the segment is lost, and cannot be recovered. 


cS) If the MSOPEN which created the segment specified DISP=NAMED, and if the 
MSCLOSE which releases it specifies DISP=SAVE, then the segment's disk 
file Cand the information it contains) is retained. The real pages 
containing portions of the segment's data are written onto the disk file 
before being released. 
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Size Limits of Virtual Data Segments 


There are two aspects to the size of a virtual data segment: virtual size and 
real size. The virtual size of a segment is the number of uniquely 
addressable memory locations within the segment; the real size of a segment is 
the amount of physical memory which is used to hold portions of the virtual 
segment during processing. 


The upper Limit of a segment's virtual size is Limited by two factors: 


1. The Limit of the hardware's ability to represent addresses. The DPS-8 
virtual-memory hardware is capable of accessing 4 billion (actually 
4,294,967,296) unique word addresses; no virtual data segment may exceed 
this size. 

Note: References to hardware in the following discussion refer to the 
DPS-8, L66, or any other hardware on which the CP-6 operating system can 
run. 


2. Special addressing techniques are necessary to access any address within a 
virtual segment which Lies at any address above the 256K-word boundary. 
These techniques are discussed in more detail later. 


The upper Limit of a segment's real size is dictated to a large extent by the 
segment's virtual size, as follows: 


1. If the virtual size of a segment is 2 mega-words (2048 pages) or less, 
then the segment's real size may vary from 6 pages to the current virtual 
size (or the remainder of the user's memory authorization, whichever is 
less). In this situation, it is possible to have a virtual segment which 
is completely memory resident; no "missing page" faults occur, and no disk 
I/0 is necessary. 


2. If the virtual size of a segment exceeds 2 mega-words (2048 pages), the 
upper Limit of the segment's real size is 256 pages. This sharp reduction 
in the real size Limit occurs because the virtual-segment manager must use 
a "fragmented" page table to keep track of the segment's real memory; such 
a table is Limited by the hardware to 256 entries. 


Addressing Data within a Virtual Segment 


Data within a virtual segment is addressed in much the same way as data within 
any data segment is accessed: through PL-6 "PTR" variables, pointing to other 
PL-6 variables which have been declared "BASED". 


Unfortunately, some fundamental Limitations of the hardware make accessing 
large virtual segments rather more difficult than the previous statement would 
imply. The hardware is designed primarily to access data which Lies within 
segments not exceeding 256K words in size. Pointer registers (Cand "PTR" 
variables in PL-6, of course) contain an 18-bit field which contains the "word 
displacement from the beginning of the segment"; index registers are only 18 
bits wide; addressing calculations are performed in an 18-bit modulus 
arithmetic; and so forth. 


There are three practical ways in which the programmer may work around these 
hardware Limitations: 


1. Never use a virtual segment that exceeds 256K words in size. If this size 


Limit is honored, a virtual segment may be addressed in exactly the same 
fashion as any other data segment. 
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2. Generate one or more secondary descriptors, which permit access to 
portions of a virtual segment which Lie above the 256K-word address 
boundary. In effect, this method breaks up one Large virtual segment into 
a number (up to 16) of smaller segments, each of which is up to 256K words 
in size. Each of these smaller segments has a unique "segment ID", and 
may be addressed as a distinct area of memory. 


3. Use the hardware's “extended addressing" instructions to directly access 
any location within the virtual segment. 


Method 1 can be performed entirely in PL-6; methods 2 and 3 each require some 
programming in GMAP or BMAP (DPS-8 assembler) or FORTRAN, as they involve the 
use of some DPS-8 instructions which the PL-6 compiler never generates. 


Method 1: Small Virtual Segments 


This is certainly the easiest way to use virtual segments. Using this method, 
a program may access up to three virtual data segments of 256K words each, for 
a total virtual data area of 768K words. Each of the three virtual segments 
may be accessed in the same fashion as a normal (non-virtual) data segment. 
Data in the segments may be accessed through PL-6 "PTR" variables which point 
to suitable "BASED" variables, and the data may be passed to other PL-6 or 
FORTRAN procedures through the normal parameter-passing channels. 


No assembly-~lLanguage code is required when using this method. 


Method 2: ’Divide and Conquer 


This method operates by breaking a single (large) virtual segment up into a 
set of smaller segments, each of which is 256K words or Less in size. In the 
current version of the CP-6 system, it is possible to create up to 16 of these 
sub-segments, thus permitting a program to simultaneously access up to 4 
mega-words of virtual memory. Each sub-segment has a unique "SEGID" (segment 
ID number), and is treated as a completely self-contained section of memory. 
It is not possible to “access across" the boundary between two of these 
sub-segments without causing a fault to occur; each BASED structure allocated 
by the user must Lie completely within one of these segments. 


To use this method, the user's PL-6 program must call a special-purpose 
routine written in BMAP assembler; this routine executes the instructions 
necessary to create and store NSA descriptors which frame up to 16 256K-word 
sub-segments, and return PL-6 "PTR" variables which may be used to refer to 
these sub-segments. 


Figure 8-7 contains a sample PL-6 routine which creates a virtual segment and 


calls the BMAP routine called "SHRINK". Figure 8-8 contains the "SHRINK" 
routine itself. 
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SETUP_SEGMENTS: PROC (NSEGS, SEG PTRS$) ALTRET; 


“INCLUDE CP_6; 


DCL NSEGS SBIN; /* input; number of 256K-word subsegments */ 
DCL SEG PTRSS (0:15) PTR; /x output; PTRs to subsegments */ 


DCL I SBIN; 
DCL VIRTUAL_SEGMENT DCB DCB; 


%FPT_OPEN (FPTN=OPEN VIRTUAL SEGMENT, 
DCB=VIRTUAL_SEGMENT DCB, 
ASN=FILE, ORG=KEYED, FUN=CREATE, DISP=SCRATCH, 
VIRTUAL=VLP_VIRTUAL); 


AVLP_VIRTUAL CFPTN=VLP_VIRTUAL, 
SEGNUM=VS1); /* could use VS2 or VS3 instead... 


DCL SHRINK ENTRY (4); 
IF NSEGS < 1 OR NSEGS > 16 THEN ALTRETURN; /* illegal call 


VLP_VIRTUAL.SEGSIZE# = NSEGS * 256 * 1024; /* 256KW each 
VLP_VIRTUAL.PHYSICAL# = NSEGS * 6; /* minimum recommended 


CALL MSOPEN (OPEN VIRTUAL SEGMENT); 
DO I = 0 TO NSEGS - 1; 
CALL SHRINK CVLP_VIRTUAL.PTRS, /x base of VDS 
I * 256 * 4096, /* byte offset from VDS base 
256 * 4096, /* size of sub-segment, in bytes 
SEG PTRSS$(I)); /* pointer is returned here... */ 
END; 
RETURN; 
END SETUP_SEGMENTS; 


Figure 8-7. PL-6 Routine to Set up Sub-segments 
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SHRINK 

SHRINK 

CALL SHRINK (Cbase$, offset, size, newS); 

"base$" points to the base of a virtual data segment; 
"offset" contains a byte offset into the segment; 
"size" contains the byte size of the resulting "shrink" 
operation. 

OUTPUT: "new$" contains a pointer corresponding to a new entry on 
the argument stack, which contains the shrunken 
descriptor. 

DESCRIPTION: This routine is used to perform a “normal shrink" 
operation on a segment framed by an NSA sSuper-descriptor. 
The shrunken descriptor is saved on the hardware argument 
stack, and a pointer corresponding to the new AS entry is 
returned to the user. 

USE SHRINK, 1 

ENTDEF SHRINK 

ENTREF X66 AUTO 4 

ENTREF X66_ARET 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 

EQU 


J 


+ + + + * + FH HH HF HF HH 
ver VVwsds VV Www vs 
+ + + % FF F HF HF HF HF HF HF 


NOU EWN AP ONAUFWN =O 


SHRINK TSXO X66 AUTO 4 Set up AUTO and get parameters 
ZERO 
LOP1 Pointer to new size 
LDQ Get size 
QLs Shift byte count into place 
SBLQ =0200000, DL Make "byte count” into "byte bound" 
ORQ WIFLGS Add all flags & "normal shrink" info 
STQ SHRVEC Save in "shrink" vector 
LOPO 3,,PR2 Pointer to "base" 
LOP1 4,,PR2 Pointer to “offset" 
LDP? 0,,PRO Get "base" 
LDEA?7 0,,PR1 Set location field in descriptor 
LDD6 SHRVEC Shrink DR7 into DR6, self-id 
SDR6 0 Push shrunken descriptor onto AS 
LDP3 6,,PR2 Get pointer to result area 
STP6 0,,PR3 Save new pointer 
TSX2 X66_ARET Return to user 


Constant data for SHRINK routine 
000000177640 
Temp data area 


SHRINK _DATA,O 
SHRVEC 0,000000001777 


Figure 8-8. BMAP Utility Sample Routine ‘SHRINK' 
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The SHRINK routine pushed new descriptors onto the hardware "argument stack". 
Space on this stack is quite Limited, and is used for a number of purposes 
Cincluding passing data to the CP-6 monitor when a monitor service routine is 


called). Therefore, programmers using method 2 should obey the following 
rules 


Never push more than 16 descriptors onto the argument stack. If you push 
too many descriptors onto the stack, your program may abort with an 
"Argument stack is full" fault at some tater time; this fault causes the 
entire contents of the argument stack to be discarded. 


Method 3: Direct Accessing 


It is possible to use the LDEA ("Load Extended Address") instruction in a way 
which permits a program to directly access the entire 4-gigaword address space 
permitted by the hardware. This technique cannot be used directly by a PL-6 
program, as the PL-6 compiler has no knowledge of the LDEA instruction or of 
data structures larger than 256K words. Therefore, it is necessary to use 
BMAP (Cor GMAP) to access Large virtual data segments in this fashion. 


The LDEA instruction operates by inserting a "byte offset" value into a 
descriptor register. This byte offset is not subject to the usual 256K-word 
segment Limitation, and thus "adjusts" the descriptor register to access data 
which Lies anywhere within a virtual data segment. 


Figure 8-9 shows a simple BMAP instruction sequence which might be used to 
access a single data word within a NON-virtual data segment. Figure 8-10 
shows the corresponding sequence which can be used to access a data word 
within a large virtual segment. 


WORD OFFSET get word offset 
SEGMENTS get pointer to segment 


0,A,PR1 Load data from segment/offset loc 
RESULT store it away 


Figure 8-9. Accessing Data within a Standard Segment 


WORD OFFSET get word offset 
2 shift Left 2 bits to convert 
TEMP to byte offset, then save it 


SEGMENTS get ptr to base of VDS 

TEMP insert byte offset into DR1 
0,,PR1 load data from extended address 
RESULT save it 


Figure 8-10. Accessing Data within a Large Virtual Segment 


Further details concerning use of the LDEA instruction may be found in the 
"DPS-8 Assembly Instructions" reference manual Corder number DHOQ3). 
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Performance Considerations 


The “cost" of using a virtual data segment depends on a number of factors: 
e The virtual size of the segment. 


@ The number of real pages which are allocated to retain portions of the 
virtual segment. 


e The locations within the segment of the data actually accessed by the 
program. 


A virtual data segment is most efficient when most (or all) of those portions 
of the segment which are actually being accessed can be retained in real 
memory. In this situation, few or no “missing page" faults occur, and little 
or no disk I/0 occurs; the program using the segment can run at "full speed". 
If the number of pages being frequently accessed by the program exceeds the 
number of real pages assigned to the segment, a condition known as "thrashing" 
may occur, and performance deteriorates drastically. One might consider 
"thrashing" to be the point at which the system is spending more time swapping 
virtual-memory pages than it is doing useful work. 


At any particular time during its execution, a program usually tends to 
concentrate its efforts on a subset of the data available to it. This subset 
is generally called the program's “working set"; the working set changes with 
time, and may expand or contract substantially during different phases of a 
program's execution. 


Guidelines for Virtual/Real Segment Sizing 


Experience has shown that if the size of the working set is greater than three 
times the real memory size available, then the system will suffer from an 
unacceptably high rate of missing-~page faults and thrashing. There are two 
ways to prevent a virtual-memory system from thrashing: 


e Increase the amount of real memory used to hold the virtual segment. 


e When allocating space within the virtual segment, cluster related data 
together. This tends to reduce the size of the working set. 
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Accounting Considerations 


Use of a virtual data segment results in resource-use charges in a number of 
categories: 


1. Real memory usage (Cin "page-minute" units). This charge depends on the 
number of pages of real memory actually used to hold the virtual segment 
(derived from VLP VIRTUAL.PHYSICAL#) and on the amount of CPU time used by 
the program. ~ 


2. User service time. When a page fault occurs, the virtual segment handler 
generally issues a single MSWRITE followed by an MSREAD. The time 
necessary to perform these services is combined as the "user service" 
category. 


On a DPS-C central processor (L66 high-speed model used as the "1.0 
performance multiplier"), the MSWRITE/MSREAD sequence generally requires 
between 8 and 10 milliseconds of CPU time (ptus whatever "I/0 wait" time 
is required by the disk drives; this time is not charged to the user). 


3. PMME (monitor service) and disk I/0. Generally, each page fault causes 
the virtual segment handler to issue 2 PMMES, and between 4 and 8 disk 1/0 
operations. 


The actual charges which a particular program incurs depend on the rates set 
by the CP-6 system manager. If, at an installation, memory usage is cheap and 
disk access is dear, the system manager can minimize charges by increasing the 
amount of real memory assigned to the program's virtual segments. On the 
other hand, if a site is memory-conscious and charges heavily for memory 
usage, and charges Little or nothing for disk activity, then reducing the 
amount of real memory assigned to the virtual segments will probably cut costs 
(although the program will probably require more wall-clock time to execute). 


Restrictions and Programming Considerations 


The CP-6 monitor expects all FPTs, VLPs, buffers, etc. to be available in real 
memory whenever a monitor service request is called; it does not recover from 
a "missing page" fault when accessing any of these items. Therefore, it is 
NOT POSSIBLE to reliably pass portions of a virtual data segment to the CP-6 
monitor, for use as I/0 buffers or service parameters. To read data into a 
portion of a virtual data segment, the program should read the data into a 
temporary buffer in STATIC or AUTO memory, and then move it to the appropriate 
Location(s) in the virtual segment; a similar technique should be used for 
writing data in a virtual segment. Do NOT attempt to place FPT or VLP 
structures in a virtual segment. 


If access method 3 (LDEA Extended Addressing) is being used to address data in 
a large virtual segment, it is impossible to take the ADDR of data in the 
segment, or to pass portions of the segment to PL-6 (or any other) subroutines 
through the standard parameter-passing techniques. 


Certain Extended Instruction Set (EIS) operations are sensitive to being 
interrupted and restarted (as may happen if a missing-page fault occurs). In 
particular, EIS instructions with a result operand that overlaps any source 
operand may not operate properly under these conditions. Bit- and byte-string 
manipulation instructions (MLR, MRL, CSL, and CSR) are particularly vulnerable 
to errors in situations of this sort. 
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As mentioned above, the performance of a virtual data segment depends very 
strongly on the amount of real memory assigned to the segment, and on the 
amount of virtual memory actually used by the program. Thus, a program which 
uses a virtual segment should be capable of determining the amount of real 
memory actually available, and should use a reasonable portion of that memory 
for the virtual segment. This may be done by making proper use of the M$GDDL 
service, which determines the number of pages of real memory which may be 
acquired by the program. The user may then "tune" the program's behavior by 
changing the value of the MEMORY option on the !RESOURCE, !ORES, or !LIMIT 
command. 


For example: 
ZINCLUDE CP_6; 


%FPT_GDDL (RESULTS=VLP_GDDL); 
%VLP_GDDL; 


ZFPT_OPEN CFPTN=OPEN VIRTUAL, DCB=VIRTUAL DCB, VIRTUAL=VLP_VIRTUAL); 
CALL MSGDDL CFPT_GDDL); 
VLP_VIRTUAL.PHYSICAL# = VLP_GDDL.AVAIL PGS# / 2; 
CALL MSOPEN COPEN VIRTUAL); 


This program fragment assigns 50% of the remaining memory space to the virtual 
data segment. 
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Section 9 


Techniques: Communications 


This section contains descriptions of interfaces to the CP-6 communications 
software. This discussion is not exhaustive, but is intended to provide 
useful examples. 


Terminal I/O Control 


Although the CP~-6 FEP provides a rich variety of automatic formatting 
features, which enable the FEP to optimize throughput to devices that have 
positioning and optimizing hardware built in, sometimes these features are not 
desired. One example of a situation where the automatic FEP Line wrapping and 
Spacing are not desired might be in an application which wishes to take full 
advantage of the incremental positioning of a print head on a specialized 
device designed for text printing. By using the TERMINAL organization on a 
DCB, coupled with the TRANS=YES option on M$WRITE, the application will be 
able to send ESCAPE sequences, carriage return/linefeed sequences, and tab 
characters necessary to get the desired performance from the device, and 
bypass the CP-6 FEP automatic formatting features. 


In Figure 9-1, the ORG=TERMINAL option is used on the device open to guarantee 
passage of certain characters directly to the device, such as ESCAPE and other 
characters from the first few rows of the ASCII chart. In addition, TRANS=YES 
(transparency) is used to indicate that the application program also handles 
carriage control and intends to bypass the automatic Line-wrapping at !PLATEN 
width. Note that the BIN=YES (binary data) option is not used. This : 
application is passing one byte of ASCII information per host (9-bit) memory 
byte. With ORG=TERMINAL and TRANS=YES, the ninth bit is automatically 
stripped when passing the byte from the host to the FEP. The binary option, 
when used, would guarantee passage of all the bits in the I/0 buffer to the 
FEP, including the ninth bit. In this case, since the data is arranged one 
byte per byte, ORG=TERMINAL on the MSOPEN and TRANS=YES on the MSWRITE is 
sufficient. 
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%FPT OPEN (FPTN=OPEN DSI TERM, 
ASN=DEVICE, 
ACS=SEQUEN, 
DCB=FSDSI, 
DISP=NAMED, 
FUN=CREATE, 
ORG=TERMINAL); 


“FPT WRITE CFPTN=WRITE BUFOUT 
BUF=BUFOUT, 
BP=YES, 
DCB=F$DSI, 
TRANS=YES, 
WAIT=YES); 


ra 


/*M* DSIDUMP ~ contains machine-specific plotting subroutines */ 
/*X* DMR,PLM=5,IND=5,CTI=5,SDI=5,MCL=10,CSI=0,ECI=0,DTI=2 */ 
ZSET LISTSUB='1'B; 
[xx / 
DSIDUMP: PROC (CHARS , COUNT , FIN); 
/x 
CHARS IS CHARACTER ARRAY 
COUNT IS CHARACTER COUNT 
FIN < 0 => FORCE DUMP TO 
TERMINAL 


*/ 
DA IK RII IIR IORI IOI TOK KOT RI Rk 
ARGUMENTS 
RRR KKK RRR RIK RRR KR RR RK a | 
DCL CHARS (0:0) CHAR(1) CALIGNED; 
DCL COUNT _ SBIN WORD; 
DCL FIN SBIN WORD; 


/x 
LOCALLY NEEDED %SUBS 


SSUB TRUE#='1'B /*TRUEH*/; 
%SUB FALSE#='0'B /*FALSEA*/; 


/* 
INCLUDES 


ZINCLUDE CP_6; 
ZINCLUDE CP_6 SUBS; 
XFSOCB; 


EXTERNALS 


DCL FSDSI DCB; 
DCL FSDSIN DCB; 


DCL 1 STATS SYMREF, 
NUMCHARS 
PRTCHARS 
PLTREADS 
WIPEMEMS 
PUSHBAKS 
FILEREAD 
FILEWRTE 
TERMWRTE 


Figure 9-1. PL-6 Subroutine to Control Terminal 1/0 (cont. next page) 
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LOCAL STORAGE 


FSOSIS PTR STATIC; 


CHAR_COUNT SBIN WORD STATIC ALIGNED INIT(O); 
DCL CHAR MAX SBIN WORD STATIC ALIGNED INIT(72); 
DCL ETX_OUT_ SBIN WORD STATIC ALIGNED INIT(O); 

ETX ERRORS SBIN WORD STATIC SYMDEF ALIGNED INIT(O); 


BUFOUT CHAR(255) STATIC; 
BUFOUTU (0:254) REDEF BUFOUT CHAR(1) CALIGNED; 


HERE1CE BIT(1) ALIGNED STATIC INITCFALSE#); 
FLOW BIT(1) STATIC ALIGNED INITCFALSE#); 


ESC CHAR(1) STATIC CALIGNED INITCBITASC('033'0)); 
DCL ETX CHAR(1) STATIC CALIGNED INITCBITASC('003'0)); 
DCL PROMPT  CHAR(1) STATIC INITC'@A'); 

DCL READ BUF CHAR(1) STATIC INITC' '); 


I SBIN WORD STATIC; 
RECS UBIN WORD STATIC SYMDEF ALIGNED INIT(O); 


BAUD _RATES(0:15) STATIC SBIN HALF INIT ¢ 
ok /x 50 */ 
/*e 75 x/ 


/x 134 */ 


/* 1050 


/*x 1800 
ay /* 2000 */ 


<1, /* 2400 */ 
hg /* 4800 */ 
“Tt, /* 9600 */ 


/* 19200 */); 


DCL LINESPEED SBIN WORD STATIC SYMDEF INIT(-~1); 


YEJECT; 


%FPT_EOM CFPTN=SET_EOM, 
DCB=MSUC, 
EOMTABLE=D00 DAH); 


ZVLP_EOMTABLE (FPTN=D00_ DAH, 
VALUES="10, 44, 0, 47, 0*12"); 


%FPT_ PROMPT (FPTN=PROMPT FLOW, 

TRANS=YES, 
DCB=MSUC, 
PROMPT=PROMPT_, 
VFC=YES); 


Figure 9-1. PL-6 Subroutine to Control Terminal I/0 (cont. next page) 
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4FPT_OPEN CFPTN=OPEN FLOW, 
DCB=FSDSIN, 
ASN=DEVICE, 
FUN=IN, 
ORG=TERMINAL, 
RES='"ME'); 


%FPT CLOSE CFPTN=CLOSE FLOW, 
DCB= FSDSIN); 


%FPT READ (FPTN=READ FLOW, 
DCB=FSDSIN, 
BUF= =READ BUF, 
WAIT=YES); 


%FPT_OPEN (FPTN=OPEN DSI_TERM, 
ASN=DEVICE, 
ACS=SEQUEN, 
DCB=FS$DSI, 
DISP=NAMED, 
FUN=CREATE, 
ORG=TERMINAL); 


%~FPT_OPEN (FPTN=OPEN DSI FILE, 
DCB=FSDSI, 
ASN=FILE, 
ACS=SEQUEN, 
DISP=NAMED, 
FUN=CREATE, 
EXIST=NEWFILE, 
CTG=YES, 
ORG=CONSEC, 
REASSIGN=YES); 


[*/ 
%FPT WRITE CFPTN=WRITE BUFOUT, 
BUF=BUFOUT, 
BP=YES, 
DCB=FSDSI, 
TRANS=YES, 
WAIT=YES); 


ZFPT_GLINEATTR CFPTN=FETCH _SPEED, 
LINEATTR=SPEED _TABLE); 


AVLP_LINEATTR (FPTN=SPEED TABLE); 


XEJECT; 


Jk 
Begin DBS I DUMP main 


IF NOT HERE1CE 
THEN 
DO; 
HERE1CE = TRUE#M; 
FSDSIS = DCBADDRC(DCBNUM(FS$DSI)); 
IF FSDSI$S -> FSOCB.ASN# = XDEVICE# 
THEN 
D0; 
CALL MSOPEN COPEN DSI _TERM) ALTRET (BLEW IT); 
CALL MSOPEN (OPEN FLOW) ALTRET (BLEW IT); 
CALL MSPROMPT (PROMPT_ FLOW) ALTRET (BLEW i oe i i 


Figure 9-1. PL-6 Subroutine to Control Terminat I/0 Ccont. next page) 


CE62-00 Terminal I/0 Control 9-4 


CALL MSEOM (SET EOM) ALTRET (BLEW IT); 
CALL M$GLINEATTR (FETCH SPEED) ALTRET (BLEW IT); 
LINESPEED = BAUD _RATES(SPEED TABLE.LINESPEED#); 
IF LINESPEED = -1 
THEN 

GOTO BLEW IT; 


FLOW = TRUER; 


/xx/ 
END; 
ELSE 
IF FSDSIS -> FSDCB.ASNH = X%FILEF 
THEN 
DO; 
CALL MSOPEN (OPEN DSI FILE) ALTRET (BLEW IT); 
FLOW = FALSE#; 
END; 
ELSE 
GOTO BLEW IT; 
END; /* DO IF 1ST TIME */ 
DO WHILE CFALSE#); /* ALTRET HANDLER */ 
BLEW IT: ; 
~ CALL MSXXX; 
END; /* DO WHILE ALTRET */ 
/**/ 
/«x/ 
/xx/ 
IF FIN < 0 
THEN 
DO; 
CALL WRITE; 
RETURN; 
END; /* DO IF DUMP REQUESTED */ 
/*x*/ 
IF CHAR COUNT + COUNT >= CHAR _MAX 
THEN 
CALL WRITE; 
DO I = 0 TO COUNT - 1; 


BUFOUTUCCHAR COUNT) = CHARS (1); 
CHAR COUNT = CHAR _COUNT + 13 


END; 


/* DUMP EACH CHARACTER IN */ 


IF CHAR COUNT >= CHAR MAX 


THEN 


CALL WRITE; 


RETURN; 


WRITE: PROC; 


/x«/ 
/* FROM THIS ROUTINE */ 
/«*/ 


/* INTERNAL ROUTINE "WRITE" */ 


[xx / 
IF FLOW 
THEN 
DO; 
BUFOUTUCCHAR COUNT) = ETX; 
CHAR COUNT = “CHAR COUNT + 1; 
ETX OUT_ = ETX_OUT_ + 1; 
/xx/ 


WRITE BUFOUT.BUF .BOUND = CHAR COUNT - 1; 
CALL M$WRITE (WRITE _BUFOUT) ALTRET(WHO__ CARES); 
STATS. TERMWRTE = STATS. TERMWRTE + 1; 


WHO CARES: ; 


Figure 9-1. 
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Terminal I/0 Control 


RECS. = RECS. (+> 93 


IF ETX_OUT > 1 


READ ACK: 


# 
CALL MSREAD (READ FLOW) ALTRET CREADALT); 
DO WHILE (FALSE#); 
READALT: ; 
ETX_ERRORS = ETX_ERRORS + 1; 
END; 7* DO WHILE ALTRET */ 


ETX OUT = ETX OUT_ - 1; 
END; - /* DO IF WAITING FOR ACK */ 
Jax] 
/xx/ 
IF FIN < 0 
AND 
ETX OUT > 0 
THEN eS ! moe 
GOTO READ ACK; 
END; /x DO IF FLOW CONTROL */ 
ELSE 
DO; /* IF TO FILE */ 
WRITE BUFOUT.BUF_.BOUND = CHAR COUNT - 1; 
CALL MSWRITE (WRITE BUFOUT) ALTRETCALTWRITE2); 
STATS. TERMWRTE = STATS.TERMWRTE + 1; 
ALTWRITE2: ; 
CHAR_COUNT = 0; 
RECS = RECS + 1; 
/xx/ 
END; /x DO IF WRITING TO FILE */ 


RETURN; 
END WRITE; 


END DSIDUMP; 


Figure 9-1. PL-6 Subroutine to Control Terminal 1/0 
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Transparent I/O for Asynchronous Graphics Terminals 


Sending data in transparent or non-transparent mode to asynchronous graphics 
terminals (such as the Tektronics 40xx series) requires a thorough 
understanding of the specific terminal in use as well as the particular 
communications network in which the terminal is to operate. 


Transparency and MSWRITE 


The following parameters control transparent operation at write (and read) 
operations: fpt.DVBYTE.BIN#, fpt.DVBYTE.TRANS#, and dcb.ORG#. These 
parameters affect the write operation as follows: 


1. If dcb.ORG# = ZUR, the characters in the buffer are run through the "unit 
record” translation table, which converts all non-printable characters to 
blanks. If dcb.ORG# = ZTERMINAL, the characters are not so translated. 


2. If fpt_write.V.DVBYTE.BIN# is set, the data in the buffer is sent to the 
FEP in binary mode. ALL bits in the data are significant; each 
double-word in the buffer (72 bits) results in the transmission of nine 
8-bit ASCII characters. 


If fpt_write.V.DVBYTE.BIN# is not set, the data is sent to the FEP in 
ASCII mode. Each 9-bit byte in the buffer has its high-order bit stripped 
off, and the remaining 8 bits prepared for transmission. 


3. If fpt_write.V.DVBYTE.TRANS# is set, the 8-bit characters derived from 
step (2) above are transmitted exactly; no output optimization, tab 
expansion, or cursor positioning Cincluding VFC and CR/LF) is done. If 
fpt_write.V.DVBYTE.TRANS# is not set, the data is processed through the 
output optimizing logic, has its parity set as appropriate, and is sent. 


Transparency and M$READ 


MSREAD behaves almost as an mirror image of MSWRITE. If a transparent-mode 
read is issued, the data characters received on the Line are stored in the 
user's buffer (Cin ASCII mode only, BINary input from ASYNC Lines is not 
implemented); the CP-6 input editing functions (escape sequences, backspace, 
DEL, etc.) and echoing are disabled. When using a transparent read, the “read 
complete" condition can occur from one of several causes: 


e Enough bytes have been received to fill the user's buffer completely; 

e An activation character has been received and the program specified (via 
the MSSTRMCTL service, with the flag VLP_TRMCTL.V.ACTONTRNA#A set) that 
transparent-mode reads are to honor the current activation character set 
(which may be specified via the MSEOM service); 

e or, a read timeout condition (specified by M$EOM) has occurred. 


Issuing a transparent-mode read puts the terminal into transparent-input mode; 
the terminal remains in this mode until a non-transparent read is issued. 
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Performing Transparent/Non-transparent I/O 


To perform I/0 with a Tektronics (or HP, or any other) graphics terminal which 
expects to send and receive transparent data, first, open a DCB to the ME# 
device, specifying FUN=UPDATE and ORG=TERMINAL. This ensures that unit-record 
translation is not performed. 


To output to the terminal, issue one or more MSWRITE requests with the 

fpt write.V.DVBYTE.TRANS# bit set. Whenever possible, it is preferable to 
buffer large amounts of information in the host and to issue big MSWRITES (<= 
2048 bytes) to the output DCB. While short (e.g., 10-byte) writes will work, 
the overhead involved in performing rapid burst of short writes can 
significantly degrade the performance of both the host program and the FEP 
being used. 


To perform an operation such as "return current position of graphics 
crosshairs", use a sequence such as the following: 


1. Write any output currently buffered (see step 2 under "Transparency and 
MSWRITE"); 


2. Issue an MSTRMPRG service request, specifying that any input currently in 
the FEP's buffers be discarded; 


3. Issue an M$EOM service, setting the read timeout to 1 ten-millisecond 
interval (the minimum); 


4. Issue a I-byte transparent MS$READ. Expect this read to ALTRET with a 
“read timed out" indication; if it returns normally, go back to step 2. 
This process will help to ensure that any input that the user may have 
typed ahead will be flushed and will not interfere with the 
terminal-enquiry operation, and will ensure that the terminal is placed in 
transparent-input mode before the response to step 6 is received (which 
might not happen on a heavily-loaded FEP if this step were omitted). 


5. If the operation being performed is one in which the terminal is supposed 
to answer immediately (e.g., “report terminal status"), issue an MSEOM 
specifying a timeout value somewhat greater than the communication 
network's end-to-end turnaround delay plus the time required for the 
terminal to respond (e.g., approximately 5 seconds for a Tektronics 
connected to a local FEP). If the operation being requested requires the 
terminal user to take manual action (e.g., "position crosshairs and hit a 
key, please"), issue an MS$EOM specifying a timeout value of 0 (to disable 
timeout) or of 1 minute (for example). 


6. Issue a transparent MSWRITE, sending the character sequence to make the 
terminal perform the necessary "answerback". 


7. Issue a transparent M$READ, specifying a buffer large enough for the 
terminal's most verbose response. This read may ALTRET with a “read timed 
out" if the terminal sends fewer bytes than the buffer specified; this 
condition must be handled in a fashion appropriate for the terminal in 
question. 


8. Issue an MSEOM service specifying TIMEOUT=0 to disable the read timeout. 


NOTE: Performing only steps 1 and 5-8 may be sufficient for some graphics 
terminals. However, taking steps 1-8 ensures correct operation. 
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Use of Comgroups 


The program shown in Figure 9-2 illustrates the use of comgroups. To make the 
example more interesting, two comgroups are used. AS in most comgroup 
applications where the data coming in from the comgroup arrives in bursts, it 
is desirable to use no-wait I10. This allows the program to perform other 
tasks when there is no activity on the comgroup. 


This program opens two comgroups, sets up each one to allow terminal connects 
but not DCB connects, and then starts a no-wait read on each comgroup. Data 
received from any connected terminals is written through M$LO; any terminal 
sending "OFF" will be disconnected from its comgroup. 


As with most comgroup applications (and with most CP-6 applications), there 
are several ways to perform any given task. The example below is not intended 
to be the best solution to the problem but serves to illustrate some basic 
techniques. 


The most important thing to be learned from this example is to avoid the 
temptation to place too much processing in the event routine. Most first-time 
no-wait I/0 programmers will process the event and re-issue the read in the 
event routine, which can lead to disaster. 


When an event occurs, the current program status is placed in the user's TCB 
which is treated as a push down stack. A RETURN from the event handler pops 
the stack, and control returns to the point where the event took place. If 
another read is started while still in the event routine, before the stack is 
popped, another event can occur and another frame can be pushed. The number 
of frames the TCB can hold is a LINK option, but there is a finite Limit. 
Eventually, if the comgroup has several records in it that the read will 
satisfy, and a read is re-issued before the stack is popped, the stack will 
overflow. Even using the DO INHIBIT feature will not prevent stack overflow, 
because any monitor service call creates an opportunity for event processing 
to occur. 


Therefore, the suggested course is the one shown below: save the pertinent 
information from the stack frame, set a flag, and return. More complicated 
processes will usually utilize a linked List of events; a short cut was used 
here because of the Limited nature of the example. Since the processing to be 
done on any given event is Limited, the read is not re-issued until after all 
processing is complete; thus only one event need be saved per comgroup. An 
information table is used, indexed by comgroup number. 


The event code for both the open and the read calls is used as the index to 
the information tables. Note that the event code is offset by one, i.e., 
table index 0 is event 1. Event codes of zero have a special meaning, see the 
Monitor Services Reference Manual for more information. 


To get the most from this example, refer to the Monitor Services Reference 
Manual for the defaults taken for the various FPTs. While relatively few 

options are specified, correct running of this program depends on several 

defaults in VLP_CGCP. 


This program also makes use of the “anonymous queue". Comgroup terminals 
always write into the anonymous queue; that is why the M$READ call need not 
specify a station. Reviewing the M$READ, MSOPEN/SETSTA, and VLP_SETSTA 
defaults is essential to understanding the example. 
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/*M*x CGDEMO - Comgroup demo 
CGDEMO: PROC MAIN; 


%ZEQU CG1_READ=1; 
“~EQU CG2_READ=2; 
“EQU CG1_OPEN=1; 
ZEQU CG2 OPEN=2; 


DCL I UBIN; 


DCL CG1 DCB; 
DCL CG2 DCB; 
DCL M$LO DCB; 


DCL 1 CGTABLE (0:1) STATIC SYMDEF, 


2 PROCESS BIT(1) ALIGNED, /x set when read complete */ 

2 ADMIN BIT(1) ALIGNED, /* set by admin messages from 
the comgroup */ 

2 DCB# UBIN, /x* This comgroups DCB */ 

2 EVENT UBIN, /*x The comgroup admin message 


event, not the no-wait event, 
valid only when ADMIN jis true */ 


2 BUF_ VECTOR, /* this comgroups buffer */ 
2 ARS UBIN, /* size of current record */ 
2 STATION CHAR(8); /* name of this records originating 


station */ 


DCL CG1_BUF CHAR(140) STATIC; 
DCL CG2_ BUF CHAR(140) STATIC; 


DCL EVENT ROUTINE ENTRY ASYNC; 


ZINCLUDE CP_6; 


%EQU_CG; 
%FPT_EVENT CUENTRY=EVENT ROUTINE, STCLASS=CONSTANT); 


AFPT WAIT CFPTN=2ZZZ, STCLASS=CONSTANT, 
UNITS=86399); /* 24 * 60 * 60 -1, WAIT is mod 24 hours */ 


%FPT OPEN (FPTN=OPEN CG1, STCLASS=CONSTANT, 
ASN=COMGROUP, 

DCB=CG1, 

EVENT=%CG1_OPEN, 

NAME=CG1_NAME, 

SETSTA=MY_ STATION, 

FUN=CREATE, 

EXIST=NEWFILE, 

CTG=YES, 

SHARE=ALL, 

AU=YES); 


XFPT OPEN (FPTN=OPEN CG2, STCLASS=CONSTANT, 
ASN=COMGROUP, 
DCB=CG2, 
EVENT=%CG2_OPEN, 
NAME=CG2_NAME, 
SETSTA=MY STATION, 
FUN=CREATE, 
EXIST=NEWFILE, 
CTG=YES, 
SHARE=ALL, 
AU=YES, 
IXTNSIZE=30); 


Figure 9-2. Sample Use of Comgroups (cont. next page) 
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%VLP_NAME (FPTN=CG1_NAME, STCLASS=CONSTANT, 
NAME='"CG1"); 

%VLP_NAME (FPTN=CG2 NAME, STCLASS=CONSTANT, 
NAME='"CG2"); 


ZFPT_CGCTL (CGCP=VLP_CGCP); 


%VLP_CGCP (DCBCONLGLE=NO, STCLASS=CONSTANT, 
MAXMC=140); 


%ZFPT READ (FPTN=READCG, 
WAIT=NO); 


AVLP_SETSTA CFPTN=MY STATION, STCLASS=CONSTANT, 
MYSTATION="ME"'); 


ZFPT ACTIVATE (DISCONNECT=YES, 
STATION=DISC_ STATION); 


4VLP_STATION CFPTN=DISC_ STATION); 


/*x* Establish the event handler x/ 
CALL MSEVENT CFPT_EVENT); 


/* Open the comgroups */ 
CALL MSOPEN (OPEN CG1) ALTRET(KEEP_IT SIMPLE); 
CALL MSOPEN (OPEN CG2) ALTRET(KEEP_IT SIMPLE); 


/* Set up comgroup parameters x/ 


FPT_CGCTL.V.DCBH = DCBNUM(CG1); 
CALL MSCGCTL C(FPT_CGCTL) ALTRETC(KEEP_IT_ SIMPLE); 


FPT_CGCTL.V.DCB# = DCBNUM(CG2); 
CALL MSCGCTL C(FPT_CGCTL) ALTRETC(KEEP_ IT SIMPLE); 


/* Setup the CG fable */ 
CGTABLE.BUF (0) = VECTOR (CG1_ BUF); 
CGTABLE.BUF (1) = VECTOR (CG2 BUF); 
CGTABLE.DCB#(0) DCBNUM(CG1); 
CGTABLE.DCB#(1) DCBNUM(CG2); 


/* Issue the first reads. Subsequent reads are done in PROCESS */ 
DO I = 0 TO 1; 
READCG.V.DCB# = CGTABLE.DCBAC(I); 
READCG.BUF = CGTABLE.BUF (I); 
READCG.V.EVENT#H = I+1; 
CGTABLE.PROCESS(I) = 'O'B; 
CALL MSREAD CREADCG) ALTRETCKEEP_IT_ SIMPLE); 
END; 


/* Loop, checking for read completes using the PROCESS flag. If 
there is nothing do, goto sleep. The MS$WAIT will be interrupted 
by an event, the RETURN from the event routine comes back to the 
instruction following the MSWAIT PMME. */ 


DO WHILE ('1'B); /* DO FOREVER */ 
DO I = 0 TO 1; 
IF CGTABLE.PROCESS(I) 
THEN CALL PROCESS(I); 
END; 
/* Since a read could have completed in the interim, test flags 
again before sleep, since it will be a very deep sleep */ 


Ee | 


Figure 9-2. Sample Use of Comgroups (cont. next page) 
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DO INHIBIT; 


IF NOT CGTABLE.PROCESS(O) AND NOT CGTABLE.~PROCESS(1) 
THEN CALL MSWAIT (2222); /* A wait is always interruptable */ 
END; /* Do inhibit */ 
END; /* DO WHILE */ 


KEEP_IT_ SIMPLE: 
CALL MSMERC; /* Let the monitor print the error x/ 


/* 


This routine does the actual work, based on the contents of the 
active table entry. 

x/ 

PROCESS: PROCC(I); 


DCL I UBIN; 


DCL 1 OUTBUF STATIC, 
2 * CHAR(O) INIT('From '), 
2 STATION CHAR(8), 

2 * CHAR(O) INIT(':") 
2 * CHAR(O) INIT (' ! 
2 EVENT CHAR(20); 


o 
), 


DCL CHARS CHAR(3) BASED; 


“FPT WRITE (FPTN=WRITELO, 
DCB=M$LO); 


OUTBUF.STATION = CGTABLE.STATION(CI); 
IF CGTABLE.ADMINCI) 
THEN DO; 
OUTBUF.STATION = CGTABLE.STATION(CI); 
DO CASECCGTABLE.EVENT(I)); 
CASECZCG _TCONA); 
_  QUTBUF.EVENT='"Connected'; 
CASE(%CG_TDSCH); 
OUTBUF .EVENT='Disconnected'; 
CASE(%CG_TBRK#A); 
OUTBUF .EVENT='"Break'; 
CASECELSE); 
CALL BINCHARCOUTBUF.EVENT, CGTABLE.EVENT(I)); 
END; /* Do case */ 
WRITELO.BUF_ = VECTOR COUTBUF); 
CALL MSWRITE CWRITELO); 
END; /* Admin event */ 
ELSE DQ; /* not admin */ 
OUTBUF.STATION = CGTABLE.STATION(I); 
WRITELO.BUF = VECTORCOUTBUF); 
WRITELO.BUF .BOUND = WRITELO.BUF .BOUND - SIZECCOUTBUF .EVENT); 
CALL MSWRITE CWRITELO); 


IF CGTABLE.ARS(I) = O THEN WRITELO.BUF_ = VECTOR(NIL); 
ELSE DO; 

WRITELO.BUF_ = CGTABLE.BUF (I); 

WRITELO.BUF .BOUND = CGTABLE.ARS(I)-1; 

END; 


CALL MSWRITE (WRITELO); 


IF CGTABLE.ARS(I) = 3 AND VBASECCGTABLE.BUF (I))->CHAR3 = 'OFF' 
THEN DO; 


DISC STATION.STATION# = CGTABLE.STATION(I); 
FPT_ACTIVATE.V.DCB# = CGTABLE.DCBACI); 
CALL MSDEACTIVATE CFPT_ ACTIVATE) WHENALTRETURN DO; 

END; /* ignore ALTRET */ 


END; 
END; /* not admin */ y 


Figure 9-2. Sample Use of Comgroups (cont. next page) 
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Reset the need-to-process flag and re-issue the read 


CGTABLE.PROCESSC(I) = 'O'B; 
READCG.V.DCB# = CGTABLE.DCBACI); 
READCG.BUF = CGTABLE.BUF (1); 
READCG.V.EVENTH = It1; 
CALL MSREAD CREADCG); 
RETURN; 

END PROCESS; 

END CGDEMO; 

%EOD; 

/* 
The event routine is entered when the previously 
issued comgroup read is complete. The TCB must be big enough 
to handle concurrent events since an event from one comgroup 
can occur during processing of another. In this case, only 
two events can occur at once, which will fit in the default 
TCB size. 

*/ 

EVENT ROUTINE: PROC ASYNC; 


DCL STKS PTR; 
DCL I UBIN; 


DCL 1 CGTABLE (0:1) SYMREF, 
PROCESS BIT(1) ALIGNED, 
ADMIN BIT(1) ALIGNED, 
DCB# UBIN, 
EVENT UBIN, 
BUF_ VECTOR, 
ARS UBIN, 
STATION CHAR(8); 


ZINCLUDE CP_6; 


DCL BSTCB$ PTR SYMREF; 

%BSTCB (STCLASS="BASED (B$TCB$)"); 
XBSNWIO (STCLASS="BASED(STKS$)"); 
%BSCGAURD; 


STK$ = BSTCB.STKS; 

I = BSNWIO.EVID-1; 

IF BSNWIO.CGPARM.MSGTYPA# = '*AUEV! 

THEN DO; 
CGTABLE.ADMIN(I) 1'B; 
CGTABLE.EVENT(I) = VBASE(CGTABLE.BUF (I))->BSCGAURD.EVENT; 
END; 

ELSE CGTABLE.ADMIN(I) = 'O'B; 

CGTABLE.ARS (1)=BSNWIO.ARS; 

CGTABLE.STATION(I)=BSNWIO.CGPARM.STATIONA; 

CGTABLE.PROCESS(I) = '1'B; 

RETURN; 

END EVENT ROUTINE; 


Figure 9-2. Sample Use of Comgroups 


To create devices which can be used as terminals for this program, use the 
session shown in Figure 9-3 as an example. 
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'SUPER 
kee CP-6 SUPER BO3 *** 


CMD*CR DEV CGDEMO2 
OPT*USE=CG 
OPT*COMGROUP=CG/CG2.account 
OPT*SNAME=STATION2 
OPT*END 

STATION2 created. 
CMD*END 


keke NO Errors *x** 
zeke NO Warnings *** 


Substitute the account you 


Figure 9-3. 
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will run CGDEMO in for ".account". 


Use of SUPER for Comgroup Definition 


Use of Comgroups 


Section 10 


Shared Run Units 


Advantages of Shared Run Units 


CP-6 provides a sophisticated capability for sharing the unchanging portions 
of frequently~used run units (that is, those portions of the program which 
cannot be altered by the program). This sharing Leads to a dual advantage: 


e Total system memory uSage is greatly reduced. For example, no matter how 
many users are accessing the FORTRAN compiler, there is only one copy of 
the compiler's executable code in memory. 


e System response is substantially improved. After a shared run unit has 
been loaded into memory once, its procedure does not need to be loaded 
again when other users invoke it. Thus, users invoking the processor 
receive a much faster response; the total number of disk 1/0 operations 
decreases sharply, increasing disk throughput for other users of the same 
disk packset. 


Shared Programs 


Programs can be divided into three categories, based on their ability to be- 
shared: 


1. Programs that must be shared to operate properly. All special shared 
processors (debuggers, command processors, shared Libraries, and alternate 
shared Libraries) fall into this category. Processors such as these are 
normally placed in "shared" status when CP-6 is initialized, and remain in 
that status. 


2. Programs that cannot be shared. Programs in this class include programs 
with more than one level of overlay, programs which have been LINKed with 
the NSHAREABLE option, and programs stored in "star" files. 


3. Programs that may be shared, but need not be. Most CP-6 processors and 
user-written programs fall into this category. 


CE62-00 Shared Programs 10-1 


System Configuration to Permit Sharing 


The sharing process operates, based on three options specified in the TIGR 
deck at system initialization time: 


e The SPROC option is used to specify the name, type, and overlay count for 
a processor which is to be "always shared" (category 1). Generally, this 
option is used to List those command processors (CP), debuggers (DB), 
shared Libraries (LI), and alternate shared Libraries (AS) necessary for 
normal operation of the system. It is possible to use this option to 
specify that a standard processor (SP) should be "always shared", but this 
is not recommended. 


e The SPSPACE option may be used to reserve space in the shared-processor 
tables for additional category~1 processors, which are to be installed at 
a later time by use of the SPIDER processor. This option may be used to 
permit installations to develop, install, and test new shared libraries, 
etc. without requiring that the system be rebooted each time the new 
libraries are changed. 


e The SPAUTOSPACE option is used to reserve space in the shared-program 
tables for ordinary, shareable run units (category 3). 


Auto-Sharing Process 


The normal run-unit sharing process is performed automatically by the CP-6 
monitor; it is essentially invisible to the users of a shared run unit, and 
requires no intervention by either the system operator or the system manager. 
Programs are placed in shared status when users invoke them, and remain in 
this status until there is no further use for them. 


Programming Considerations 


Almost all programs written for the CP-6 system are capable of being shared. 
Shared programs can acquire and release memory and DCBs, access files and 
issue all but a very few monitor service requests without having to take the 
program's "shared" status into consideration. A shared program can Cif 
necessary) issue an MSUNSHARE monitor service request, which creates a new, 
unshared copy of the program's procedure on behalf of the user currently 
running the program. 


Programs written in a high level Language (FORTRAN, PL-6, PASCAL, etc.) are 
generally very good candidates for sharing, as all executable instructions and 
constants generated by these languages’ compilers are automatically placed in 
“read/execute/no-write”" memory. 


Programs or subroutines which are being written in assembler (GMAP or BMAP) 
should be coded with data stored separately from procedure and without 
self-modifying procedure in order to take advantage of the auto-sharing 
process. 


To ensure that a large, overlaid program can be shared in an effective manner, 
care should be taken when the program's overlay structure is designed. 
Specifically: 


e The program may have only one level of overlays; that is, an overlay 
cannot have other overlays subordinate to itself. 
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e The program should not have a large number of overlays at level 1. Each 
overlay in the program requires one entry in the shared-program table; a 
program with (for example) 200 overlays might not fit into the table at 
all, or might fit only if most other shared programs were purged from the 
table. 


If it is necessary to run programs with large numbers of overlays, the 
programmer should request that the system manager increase the SPAUTOSPACE 
entry in the TIGR deck to accommodate the large programs. It is also 
important to note that not all overlays of an overlaid program which is 
shared need to be in memory at once. 


Usage Considerations 


Under normal circumstances, a CP-6 user accessing a shared run unit need not 
be concerned about the program's shared status. Differences in behavior 
appear only when a shared program is being debugged via the DELTA debugger (Cor 
some other, user-written debug tool). 


The major difference between debugging a shared program and debugging an 
unshared program concerns changes to the program's "procedure™ memory pages. 
These pages may be accessed by the program, but can never be modified by the 
program itself. The DELTA debugger is permitted to modify data in the 
procedure pages of an unshared program, but cannot modify information in the 
procedure pages of a shared program (because any such modifications would 
affect every user associated with the program!). This restriction has several 
implications: 


e The user cannot use DELTA'sS MODIFY command to change instructions or 
constant data stored in the procedure portion of a shared program. 


® The user cannot set procedure breakpoints (via DELTA'sS AT) in a shared 
program's procedure. 


@ The user cannot set data breakpoints (via DELTA'S WHEN command) when 
executing a shared program, or when executing an unshared program which’ is 
associated with a shared Library. 


e The user cannot step through a shared program (via DELTA's STEP, 
STEP ONE CALL, or J] commands). 


The user may work around this restriction in one of several ways: 


e The user may choose to invoke the program via the IBEX command 
"ISTART rununit UNDER DELTA" Cor "!U" followed by "!rununit"). When a run 
unit is invoked in this fashion, the auto-sharing process is bypassed; the 
user receives an unshared copy of the program, and may proceed with normal 
debugging operations. 


e If the user associates DELTA after the program has begun executing (via a 
control~Y "!!DELTA" sequence) or after the program aborts, DELTA informs 
the user that a "shared program associated - use UNSHARE to set 
breakpoints or modify procedure". At this point, the user must issue the 
DELTA command "UNSHARE" before setting instruction breakpoints or 
modifying the program's procedure; the user must issue the command 
"UNSHARE ALL" before setting data breakpoints. 


e Some sophisticated programs make use of the M$SALIB monitor service to 
associate and pass commands to DELTA, to display data or modify the 
programs’ procedure pages or perform other interesting tasks. If programs 
modify constant data or procedure, it is necessary for the programs to to 
issue an MSUNSHARE request before issuing the initial M$ALIB, to remove 
themselves from "shared" status and thus permit DELTA to modify their 
procedure. 
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Section 11 
Special Shared Processors 


A special shared processor is a run unit that may co-exist and interact with 
the user program. It differs from shared run-time Libraries in that it 
resides in a working space other than that of the user; it is not LINKed with 
the user program. 


The CP-6 system recognizes three types of special shared processors: 


e Alternate Shared Libraries 
e Debuggers 
e Command processors. 


Only one processor of a given type may be associated with a user at any time. 
The standard CP-6 system includes I-D-S/II as the supplied alternate shared 
Library, DELTA as the debugger, and IBEX as the command processor. 
Installations may provide additional special shared processors for their own 
use in any of the three categories. 


All special shared processors of a given type reside in a dedicated working 
space quarter concurrently with one another. Working space 6 is dedicated to 
Alternate Shared Libraries, working space 5 is dedicated to debuggers, and 
working space 4 is dedicated to command processors. The page table for a 
special shared processor is also contained within its working space. 


A special shared processor run unit must consist of only pure procedure; there 
can be no DCBs or static data. Special shared processors may use the MSGETDCB 
monitor service to acquire DCBs in the user's Read-only Segment and use 
dynamic data segments for all non-constant data. <A data segment area is 
provided in each user's own working space for each type special shared 
processor. One type of special shared processor does not have access to the 
data segments of another special shared processor, nor does the user have 
access to the data segments of any of the special shared processors. Refer to 
the map of user virtual memory in the Monitor Services Reference Manual, 
Appendix E. 


It is, then, the procedure portion of a special shared processor that resides 
in its own working space. The procedure portion is shared by all users 
associated with the processor. 


Entry to a special shared processor causes a change of domain, thereby 
changing the areas of memory to which the processor has access. The areas of 
user memory to which the processor has access are determined by its type and 
are described in the discussion of each type of special shared processors. 
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Guidelines for All Special Shared Processors 


The following discussion presents information needed to create a special 
shared processor. Information that is common to the three types of special 
shared processors is included in this subsection; information that is specific 
to each type of special shared processor is presented Later in this document. 


Special Shared Processor Initialization 


Because special shared processors do not contain static data or DCBs, 
initialization for all three types of special shared processors is similar. 
The following subsections discuss interfaces and techniques available for 
special shared processor initialization. 


Processor Initialization Area (PIA) 


Sixteen words of static in the user working space are reserved for use by 
special shared processor initialization routines. This area is shared by all 
special shared processors associated with the user program, so any process 
that references that area should be inhibited to avoid being interrupted by 
another special shared processor that may also modify the contents of the PIA. 
This space is framed by a descriptor in the special shared processor's Linkage 
Segment. A pointer to this area, BSPIA$, is SYMDEFed in the module 

B_USRPTRS_ D.:sLIBRARY. If the special shared processor is not to be LINKed 
with this module, a pointer to this area may be built as follows: 


ZINCLUDE B SEGIDS C.:LIBRARY; 


DCL PIA BIT(36) CONSTANT INITC%PIASID); 
DCL PIAS REDEF PIA PTR; 


Also, this segment may be referenced in BMAP modules as follows: 


SEGREF PIASID 
LDPn PIASID,DL 
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Initial Entry and Obtaining AUTO Storage 


When a debugger or alternate shared Library is entered, it must first 
determine if this is the first time it has been called so that it may perform 
any initialization functions that may be required. The module that contains 
the special shared processor entry address must be written in BMAP, because on 
the first entry the AUTO segment must be obtained and initialized and on 
subsequent entries the AUTO stack must not be obtained, but must be 
re-initialized to its initial (empty) values. 

NOTE: Command Processors do not have this requirement as the data segments 
for a command processor are released on every MSCPEXIT service request. A 
command processor's entry module may be written in PL-6 by declaring that 
procedure as the "MAIN" procedure. A call to X66 MAUTO will be generated by 
the compiler. 


A simple test to determine if this is an initial entry to a special shared 
processor is to determine if an AUTO segment has been allocated. This may be 
accomplished as follows: 


SEGREF AUTOSID 
SEGREF PIASID 


* 
LDI =04010 Set HEX & OVRFL mask 
LDP2 AUTOSID 
LDOP1 PIASID 
INHIB ON 
STD2 0,,1 Store the AUTO descriptor in the PIA 
LXL1 0,,1 Load the descriptor access flags 
INHIB OFF 
ANX1 =0100600,DU Test Read, Not empty, Present 
ERX1 =0100600,DU 
TZE NOTFIRST Segment previously allocated, not first 


AUTO storage for a special shared processor must be in a data segment. A 
special shared processor may establish the AUTO stack by making a call to the 
appropriate routine in X6U$CSEQU which is an object unit in the :LIBRARY 
account. If the need is only to initialize AUTO for possible future use, 

X66 MSTATIC should be called. If, however, the calling BMAP module needs AUTO 
storage, X66 MAUTO should be invoked. In either case the call is: TSxO 

X66 _Mxxx. The following word is assumed to be a data word. For X66 MAUTO it 
must contain the size of the desired frame in the left half of the word 
following TSX0, and must specify an even number of words: 


ENTREF X66 _Mxxx 


TSxO X66 Mxxx 
ZERO frame size,0 


In either case return is: TRA 1,X0. 


Now that the AUTO Stack has been allocated, the BMAP entry module may call 
PL-6 subroutines to complete any initialization functions. 


The AUTO data segment may be re-initialized on subsequent entries to the 
special shared processor as follows: 


NOTFIRST 
LDP2 AUTOSID,DL Point to base of AUTO 
LDXxO -5,DU 
SXLO O,,2 Set current frame offset 
AWD 4,,2 Point to first frame 
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Obtaining DCBs 


A special shared processor must obtain its own DCBs. See the description of 
MSGETDCB in the CP-6 Monitor Services Reference Manual (CE33) for details. 
Some entries in the DCB table are reserved for special shared processors. 
These are mentioned in the discussion of each type of special shared 
processor. 


Use of Data Segments 


Because a special shared processor has no static data, it makes use of Data 
Segments in the user working space obtained via either the M$GDS monitor 
service described in the CP-6 Monitor Services Reference Manual or the use of 
the AREADEF attribute of the PL-6 compiler as described in the CP-6 PL-6 
Reference Manual. The data segments for each type of special shared processor 
while residing within the user working space are separate from the user data 
segments and are not directly accessible by the user. The M$GDS automatically 
allocates the appropriate segments based on which domain issued the M$GDS 
request. 


Once obtained, data segments remain allocated until the current user program 
is run down, with the exception of data segments for command processors which 
are released on every MSCPEXIT service request. 


Exceptional Condition Processing 


Exceptional condition processing works basically the same way for special 
shared processors as it does for user programs. Any differences are discussed 
in the description of exceptional conditions in Section 6 of the CP-6 Monitor 
Services Reference Manual. An author of a special shared processor should 
take note of: 


e MSINT - “Entry to MSINT Procedure" 
e MSEVENT - “Event Conditions and Domains" 
e MSXCON - “Exit Control and Domains" 


Also of interest are monitor services for exiting exceptional condition 
procedures that are available only to special shared processors: 


e MSINTRTIN - Return from MSINT procedure 


e MSXCONRTN - Return from MS$XCON procedure 
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Taking Snapshot Dumps 


Taking and analyzing snapshot dumps is discussed in the following subsections. 


Calling MS6SCREECH 


A special shared processor may cause an entry to CP-6 recovery for the purpose 
of creating a snapshot dump by using the MSSCREECH monitor service. One of 
the parameters of this service is the recovery code which allows the special 
shared processor to indicate what portions of the user memory and the special 
shared processor memory are to be written to the dump file. Refer to the 
following in Section 8 of the Monitor Services Reference Manual: 


e MSSCREECH - RECOVERY 


© VLP_SCODE 


Special Shared Processor Data in Dump Files 


The ANLZ processor may be used to examine data belonging to a Special Shared 
Processor. Complete information on ANLZ is contained in the CP-6 System 
Support Reference Manual (CE41). The following ANLZ commands may be useful: 


@ To examine the Special Shared Processor's Task Control Block: 
TCBCssp) nnn 

e To examine the Special Shared Processor's Data Segments: 
DU $LS4->0 USING nnn, ssp 


DU $LS5->0 USING nnn, ssp 
DU $LS6->0 USING nnn, ssp 


DU $LS11->0 USING nnn, ssp 


where nnn is CUN for the current user, or is a specific user number and 
ssp is ICP, ASL, or IDB to identify the type of special shared processor. 
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Debugging of Special Shared Processors with XDELTA 


This subsection discusses XDELTA and describes its use for the debugging of 
Special Shared Processors (debuggers, command processors, and alternate shared 
Libraries). Specified here is also some general information pertaining to the 
use of XDELTA for debugging of user programs and the CP-6 Monitor. 


XDELTA is a standalone entity which does not depend on the CP-6 Monitor for 
control or services. XDELTA uses the mini-I/0 system in AARDVARK for all its 
input and output requirements. This is the same I/0 system used at boot-time 
and by recovery. With this system XDELTA can read commands (Cusually patches) 
from cards, tape, or the console at boot-time, and can output to the console 
or the boot-time printer. The control of XDELTA at boot-time for patching is 
described in the Operations Reference Manual (CE34) under System Startup and 
Recovery. The other function of XDELTA is its use as an interactive debugger. 
XDELTA may be used to debug the Monitor, any user program, or any special 
shared processor (command processor, debugger, or alternate shared Library). 
When being used as a debugger, XDELTA uses the mini-1I/0 system for reading 
commands (from the console or card reader) and for outputting to the console 
and the printer. XDELTA reads and writes only through the I0M-connected 
system console, and will print only on the I0M-connected printer specified at 
boot time. 


XDELTA is the same as user DELTA in its general operation and command 
repertoire. The major difference is noticed when debugging entities other 
than the CP-6 Monitor when none of the program symbols are available. When 
debugging the Monitor, the Linker defined symbols (ENTDEFs and SYMDEFS) and a 
small subset of debug schema are always available along with as much 
additional schema as was specified at boot time. (See Operations Reference 
Manual, CE34, System Start-up and Recovery.) For the same reason, the @ and # 
symbols are not defined except in the Monitor. To reference the patch space 
defined by LINK's IPATCH and DPATCH options, one must DEFINE symbols for the 
Locations B_PATCHI and B_PATCHD respectively. These symbols can be found in 
the LINK map. Other general restrictions are that XDELTA has no provisions 
for handling overlaid programs and does not have a data breakpoint (WHEN) 
capability. 


Using XDELTA 


When using XDELTA to debug any domain other than the Monitor, it is important 
to remember that XDELTA references ASL, ICP, and IDB domains through some 
user's Linkage segment and page table. The USE command discussed in detail 
Later establishes which domain is to be examined. The most frequently used 
form of the USE command is as follows: 


USE USERC#nn], domain 


ALl users of the same ICP will cause XDELTA to reference the same actual pages 
of memory when referencing the ICP's instruction segment ($LS0), but all other 
references will be unique to each user. For this reason, it is usually best 
to debug a command program, ASL, or debugger which has only one user 
associated with it. In general it is best to debug these domains on a 
quiescent system if at all possible. All special shared processors are always 
shared; therefore, if a breakpoint is planted in a special shared processor 
via the address domain of one user, any other user of the same special shared 
processor can trigger the same breakpoint. 


Debugging IDBs (Debuggers) 


The following technique is useful for initially planting a breakpoint in a 
debugger: 
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1. Enter XDELTA via the DELTA keyin. 

2. Place a Monitor breakpoint at SSUSDELTAGO. 

3. GO 

4. Start up the user which associates the debugger to be tested. 

5. When the breakpoint is reached, the debugger is about to be entered. The 
USE command UU,IDB will give access to the debugger for the purpose of 
planting breakpoints. Using the LINK map for the debugger, DEFINE 


appropriate symbols for the modules to be debugged and specify the wanted 
breakpoints. 


Debugging ICPs (Command Processors) 


The following technique is useful for initially planting a breakpoint in a 
command processor: 


1. Enter XDELTA via the DELTA keyin. 

2. Place a Monitor breakpoint at SSCSACPENT. 

3. 60 

4. Start up the user which associates the command processor to be tested. 

5. When the breakpoint is reached, the command processor is about to be 
entered. The USE command UU,ICP will give access to the command processor 
for the purpose of planting breakpoints. Using the LINK map for the 
command processor, DEFINE appropriate symbols for the modules to be 
debugged and specify the wanted breakpoints. 


Debugging ASLs (CALlternate Shared Libraries) and User Programs 


The following information is useful when debugging ASLS and user programs with 
XDELTA. 


Alternate Shared Libraries are called directly from the user domain without 

involving the Monitor. For this reason it is necessary to first "catch" the 

user program before planting breakpoints in the ASL. On a quiescent system 

this may be accomplished by the following technique: 

1. Enter XDELTA via the DELTA keyin. 

2. Place a Monitor breakpoint at FMMSASSMRG. 

3. GO 

4. Cause the user program which will call the ASL to be fetched. 

5. When the breakpoint is reached, both the user program and the ASL (if any) 
will be accessible. To access the user program enter the USE command UU. 
To access the ASL enter the USE command UU,ASL. 

Note: If the system is not sufficiently quiescent to "catch" the appropriate 

user, use SPY.X to find out what user number the user program will run as. 


Then use an IF S_CUN = .nn clause on the Monitor breakpoint specified in Step 
Qe 
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Debugging ASLs at Recovery 


When debugging the portion of an ASL that is called at the time of System 
Recovery, use the following steps to set breakpoints in the ASL: 


ae Entry to XDELTA is made following the "DO YOU WANT DELTA ?" question, 
which comes out to the system console just as the system is rebooted. 
Just answer yes to the question and the system will go to XDELTA. 


2. From GHOST1's Link map, find the ENTDEF ASLSRECOVER. A Link map for 
GHOST1 can be obtained by using the Linker MAP command on the GHOST1 run 
unit supplied with the CP~6 release tape. 


3. Place a breakpoint in GHOST1 at this address. (GHOST1 is the current uSer 
at this time so just specify UU to address it.) 


4. When the breakpoint is hit, specify UU,ASL and plant whatever breakpoints 
you need to debug the ASL. 


It should be remembered that all breakpoints planted in the user by the 
debugger under test will be first reported to XDELTA. The GOTRAP command 
should be used to pass these faults on to the user program. 


Operational Considerations When Using XDELTA 


Initial entry to XDELTA may be caused by the keyin DELTA on the system 
console. This is usually adequate. If, however, this does not work or it is 
undesirable to have the KEYIN system ghost as the current user, then XDELTA 
may be entered by typing CNTRL-Y, CNTRL-Y, RETURN (Cor ESC, ESC, EOM on some 
older consoles.) 


Entry to XDELTA may also be made by causing the machine to perform an EXECUTE 
fault via the maintenance panel or DPU. This procedure is different for each 
type of CPU and is described fully in the Operations Reference Manual, CE34, 
under System Start-up and Recovery. (N.B. It is not always possible to 
proceed correctly from XDELTA if it is entered via an EXECUTE fault.) The 
EXECUTE fault may also be used to interrupt XDELTA from a Lengthy command such 
as DUMP. In this case there is no problem with continuing. 
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Addressing with XDELTA - Domain Specification 


The USE command specifies to XDELTA what is to be addressed for all memory 
references. Depending on what this command specifies, XDELTA will reference 
real memory locations, virtual Locations through a specified page table, or a 
domain of virtual space specified by some combination of linkage segments and 
page tables. When XDELTA is entered, a default USE command is assumed which 
sets addressability to the currently executing domain. This can be the 
Monitor, a user program, or an ICP, IDB, or ASL executing on behalf of a 
particular user. When this default addressability is established, XDELTA will 
address anything in the current process's domain including segments framed by 
descriptors on the argument and parameter stacks, as well as those framed by 
the current process's descriptor registers. 


USE REALC,AARDVARK]) 
USE REALC,XDELTAJ 
USE REALC,.offset] 
e.g. UR 


USE PTad.pta 
e.g. UPTA.120400 


USE MON 
e.g. UM 


USE USER,USER 
e.g. UU 


USE USER#.nn,USER 
e.g. UU#.21 


USE USER@.pta,USER 
e.g. UUa.102030 


USE USERL#.nn],ASL 
USE USERL@.ptal,ASL 
e.g. UU,A 


USE USERC#.nnj,10B 
USE USERC@.ptaj,IDB 
e.g. UU#.33,1D 


USE USERC#H.nn],ICP 
USE USERC@.ptal,ICP 
e.g. UU,IC 


USE USERC#.nn1,MON 
USE USERC@.ptal],MON 
e.g. UU#.53,M 


Addresses real memory locations directly. 
Optional argument adds appropriate bias 
for AARDVARK, XDELTA, or whatever is 
specified. 


Address through any page table. pta is 
the 18 bit page table address as it 


appears in WSPTD (word address modulo 64). 


Address through Monitor's Linkage segment 
and Monitor's and current user's page 
tables. 


Address current user through his Linkage 
segment and page table. ",USER" jis 
assumed if omitted. 


Address user number .nn through his 
linkage segment and page table. 


Address user whose page table is at 
page table address .pta through that 
page table and his Linkage segment. 
(.pta is the 18-bit word address of the 
page table modulo 64.) 


Address ASL through page table and 
appropriate linkage segment of the 
specified user. 


Address debugger through page table and 
appropriate linkage segment of the 
specified user. 


Address command processor through page 
table and appropriate linkage segment of 
the specified user. 


Address the Monitor through its page 
table and Linkage segment and the page 
table of the specified user. 


with XDELTA - Domain Specification 


USE Resets addressing to that of the executing 
e.g. U process at the time of entry to XDELTA. 
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Note: XDELTA allows data access to memory through type 1 descriptors. This 
means that the special symbols $LSR, $ASR, $PSR, and $SSR may be used as 
pointers in a pointer qualified reference such as: 


$LSR->.26 


XDELTA allows modification of memory through descriptors that have only read 
access to memory, and onto pages that are write protected. 


Control of XDELTA’s Input and Output 


The commands which affect XDELTA's input and output are READ, OUTPUT, ECHO, 
and to some extent DUMP. xXDELTA has only one input stream, which is used for 
reading commands. This input stream is directed by the READ command. The 
available sources for commands are the system console, the card reader, and, 
during the boot process only, the patch deck. The patch deck is a collection 
of input from the boot tape, the card reader, and the system console, under 
control of commands to AARDVARK. (Reference the Operations Reference Manual, 
CE34, System Start-up and Recovery.) During debug sessions, commands may only 
come from the system console or the card reader. The card reader must be the 
1OM-connected card reader known to AARDVARK at boot time. 


The READ command: 


RCEAD] PLATCH] Read commands from AARDVARK controlled 
patch deck. 


RCEADI] CCARDI Read commands from the card reader. At 
End-Of-Deck input reverts to the console. 


RCEADJ] MCE] Read commands from the system console. 


XDELTA has two output streams. One, called the echo stream, directs the 
output of echoed commands and the output of the DUMP command. (Commands are 
echoed whenever they are read from a device other than the system console.) | 
This stream is controlled by the ECHO command. The other output stream is 
called the output stream and is used for all other output Cexcept command 
prompts) and is controlled by the OUTPUT command. The only options for these 
commands are LP, ME, and NO. ME is the system console and LP is the 
I10M-connected Line printer known to AARDVARK at boot time. NO turns off the 
stream. The ECHO stream defaults to LP, and the OUTPUT stream defaults to ME. 


ECCHO] MCE Echoed commands and output of DUMP command 
go to the system console. 


ECCHO] LIP] Echoed commands and output of DUMP command 
go to the Line printer. 


ECCHOJ] NCO] Throw away output of command echoing 
and the DUMP command. 


OUCTPUT] MCE] Direct output of all commands except 
DUMP to the system console. 


OUCTPUT] LCP) Direct output of all commands except 
DUMP to the Line printer. 


OUCTPUTJ NCO) Do not print the output of commands. 


The DUMP command may optionally specify an output device, LP or ME, which jis 
effective only for the single command. 


DUCMP] ..... OCN] MCEJ 
or DUCMP] ..... OCN] LCPI 
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The LP option on these commands specifies the printer known to AARDVARK at 
boot time. AARDVARK exercises some degree of control over this device in that 
if AARDVARK is given the skip option, "S", at boot time in response to its 
request to ready the printer, AARDVARK sets a flag indicating that all 
subsequent output to that device through mini-I/0 is to be ignored. If XDELTA 
printed output is desired and this skip condition has been set, the following 
sequence must be followed to reset the flag: 


>MINI 
AARDVARK HERE 
? OU LP 
? GO 
>DUMP ..22.% 


Control of Faults 


During normal system operation, all program faults are handled by the system 
fault handler in the Monitor without XDELTA's awareness. In order to allow 
XDELTA to function, faults must be given to XDELTA whenever one or more 
breakpoints are set. This function is handled automatically by communication 
between XDELTA and the system fault handler. In order that the user of XDELTA 
have control over the handting of faults other than breakpoints, XDELTA has 
the KEEP command. The KEEP command specifies which classes of faults XDELTA 
is to report (KEEP) and which to give back to the system fault handler for 
normal processing. XDELTA will keep control of just Monitor SCREECHes, just 
Monitor faults, or all faults. When debugging the Monitor it is usually 
desirable to have XDELTA report any Monitor faults, but not user faults. When 
debugging any other domain, however, it is usually necessary to have XDELTA 
report on all faults. For this reason it is recommended that debugging of 
these domains take place on a relatively quiescent system. Whenever XDELTA 
reports a fault it brings the entire system to a halt and prompts for 
commands. XDELTA can be directed to return control of a reported fault to the 
system for normal handling with the GOTRAP command. 


KECEP] SCCREECH] Instructs XDELTA and the Monitor to give 
control to XDELTA just before any SCREECH 
occurs. This option alone does not cause 
any system overhead for fault handling, 
all faults are directly handled by the 
system fault handler without XDELTA's 
involvement. 


Note: When XDELTA reports a SCREECH, the 
current environment is that of the SCREECH 
call unless the SCREECH was caused by a 
Monitor fault in which case the current 
environment is that at the time of the 
fault. This permits, in the case of a 
Monitor fault, the commands "GO" or 

"GO Location" to continue execution 

without allowing the SCREECH to occur. 

When a SCREECH with a severity of 5 (snap) 
is reported to XDELTA, the GO command 
Causes execution to resume without creating 
the snapshot dumpfile. In order to allow 
any SCREECH to continue normally, XDELTA 
must be given a QUIT command. (N.B. If 
XDELTA is given a QUIT command at any other 
time it causes a DISK boot!) 
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KECEP] MCONJ Instructs the system to give fault control 
to XDELTA and instructs XDELTA to report 
only those faults caused by the Monitor. 
User faults, including those caused by any 
special shared processor, are handed back 
to the system for normal processing. 


KECEP] ACLLI Instructs the system to give fault handling 
to XDELTA and instructs XDELTA to report 
all faults. 


GLO] TCRAPJ Instructs XDELTA to return control of the 
currently reported fault to the system for 
normal fault processing. This is only 
valid if entry to XDELTA was caused by a 
program fault. 


Inactivation of Breakpoints by XDELTA 


Some times while debugging domains other than the Monitor, XDELTA will set 
certain breakpoints in user or special processor domains inactive. This is 
due to the fact that the user through which the breakpoint was specified has 
been run down by the Monitor and the pages which contain the breakpoints are 
no longer accessible through that user. When this occurs, KILL the 
breakpoints and start over. This will usually mean having to SPIDER in a new 
copy of the special shared processor, as the old copy will have breakpoints 
(Derail instructions) left in it. 


Guidelines for Command Processors 


A command processor is to control the conditions under which a terminal 
session or a batch job takes place. Through command processor commands, the 
user controls resources, files, devices, comgroups, and terminals and causes 
user programs and standard shared processors to be executed. 


User-written command processors reside in the command processor working space 
concurrently with IBEX and with one another. Only one command processor can 
be associated with a given user at a given point in time. 


The following guidelines are provided for the system programmer who creates a 
command processor. 
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Entry to Command Processor 


A command processor becomes associated with a user whenever: 


e The command processor has been specified via the SUPER user authorization 
CPROC option, or 


e One command processor issues an M$CPEXIT monitor service request 
specifying that another command processor be associated with a user. 


Once associated with a user, a command processor is entered at its start 
address under any of the following conditions: 


e The user is at Job Step (as is the case on the initial entry to the 
command processor). 


e The user has aborted and is about to be run down. 
e A time-sharing user has typed a Control-Y sequence on his terminal. 
® A user program has issued an M$YC monitor service request. 


There is no direct Linkage between the command processor and the user program; 
instead, the interface is in the monitor. 


The CP-6 monitor communicates the reason for entry to the command processor 
via bit settings in BSJIT.CPFLAGS1 as follows: 


CP_JSTEP#H The user jis at Job Step. 

CP_RUND# The user is about to be run down. 

CP_YC# The time-sharing user typed a Control-Y sequence. 
CP_YCPMME# The user program issued an M$YC. 


Another interesting bit in BSJIT.CPFLAGS1 is CP_LOGOFF#. This bit is set 
whenever the system detects a Line hang-up of a time-sharing terminal or an 
operator abort of a user. This bit may be set in conjunction with any of the 
other bits mentioned above. When set, it indicates to the command processor 
that no more job steps are allowed. 


Command Processor Capabilities 


The privileges afforded the command processor domain are: 

e the ability to issue an M$CPEXIT monitor service request 

e the ability to issue an MSFINDPROC monitor service request 
e the ability to issue an M$ACCT monitor service request 

e the ability to issue an MSOCMSG monitor service request 

e the ability to issue an M$SCREECH monitor service request 
e the ability to issue an M$XCONRTN monitor service request 
e write access to the JIT 


e write access to the *A file to effect DCB assignments 
(See “Effecting DCB Assignments" Later in this section.) 
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® write access to the *S file for accounting purposes 
(See MS$ACCT in Section 9 of the CP-6 Monitor Services 
Reference Manual and Appendix A of the CP-6 System 
Support Reference Manual, STARACCSKEY and ACCT_KEY.) 


DCBs for Command Processor 


There are three DCBs reserved for Command Processors. Because the first 
command processor written was called IBEX, these DCBs are called MS$IBEX, 
MSIBEX1 and M$IBEX2. These DCBs should be referred to by their EQUs jn 
CP_6 SUBS.:LIBRARY, i.e., MSIBEX#, MSIBEX1#, and MSIBEX2#, respectively. 


A command processor may also use M$DO and MSUC as appropriate. Additional 
DCBs may be acquired by issuing an M$GETDCB monitor service request, unless 
the command processor is executing on behalf of an interrupted run unit and 
has used all of the DCB slots. 


The CP-6 system generally recognizes that M$LL is used for Listing purposes by 
the command processor. This DCB is acquired dynamically, or by passing one of 
the reserved DCB numbers through FPT_GETDCB.DCBNUM_ when calling MS$GETDCB. 


If acquiring M$LL, first attempt to acquire a dynamic DCB. This is because an 
interrupted run unit may already have an M$LL defined. The command processor 
should use that DCB if possible. 


The MSUC DCB jis only useful for interacting specifically with the user 
terminal of timesharing users (not the normal command stream). At other times 
it is tied to the “bit bucket" or NO# device. 


The M$DO DCB is used for diagnostic output. If a command processor is 
effecting a DCB assignment for a user DCB that is also being used by the 
command processor (i.e. M$DO or M$LL), the command processor should close that 
DCB and reopen it to insure that the new assignment takes effect immediately. 


Effecting DCB Assignments 


A special form of the OPEN FPT, with the desired options set, is to be written 
into the *A file. The record is keyed by the name of the DCB. 


The OPEN FPT should be invoked with PFMT="PTR". This changes all the vectors 
to pointers. Any necessary VLPs should be contained in the record and should 
be pointed to by the appropriate vector name. 


DCBs #1 through #4 require some special processing. These DCBs are reserved 
for specification of files on the run unit invocation. There are four bits in 
the JIT that indicate the specification of these DCBs. They are 
BSJIT.PRFLAGS.SI, .UI, .OU and .LS. If records for these DCBs are written to 
the *A file, then the bit in BSJIT.PRFLAGS should be set. Upon re-entry to 
the command processor, if at job step (BSJIT.CPFLAGS1# & %CP_JSTEP# are true), 
these flags and the corresponding DCBs should be reset. 


Refer to the following items in Section 14 of this guide: 
e Standard Run Unit Invocation Format for Compilers 


© DCB Usage Conventions 


CE62-00 Effecting DCB Assignments 11-14 


Addressing User Memory from Command Processor 


The user's Job Information Table (JIT) is of primary interest to the command 
processor. The command processor may also receive commands in the user's 
command buffer via the M$YC monitor service. 


User's JIT 


A command processor has write access to the user's JIT through the JIT 
descriptor in the command processor's Linkage Segment. 


The fields in the JIT are described in detail in Appendix A of this manual. 
Those that are of particular interest to the creator of a command processor 
are Listed below. The command processor should take care that all other 
fields in the JIT remain intact. 


CPFLAGS1 


This word is used by the monitor and the LOGON processor to communicate job 
step information to the default command processor. Some of the flags are to 
be set by the default command processor to communicate information to the 
Logoff command processor. This word may also be used by the command processor 
to communicate information across job step. 


PRFLAGS 

This set of flags is used to pass information from the command processor to 
standard shared processors or user programs based on the run unit invocation 
Line or other commands. 

CCBUF, CCARS and CCDISP 


These fields should be set to reflect the Latest run unit invocation. 


USRERR and USRDCB 


This word contains the error code that describes why the previous run unit 
aborted. JIT.USRERR.CODE is non-zero when there is an error to report. If 
CP_EXIT# is set in JIT.CPFLAGS1 then the command processor should not report 
jt now (the exiting processor should have done so), but hold it for processing 
Later, usually in response to a question mark command. JIT.USRDCB contains 
the DCB number that was associated with this error. 


USRRNST and USRIC 

USRRNST, along with the RNST masks, is used to determine the final status of 
the previous run unit. USRIC contains the address of where the user program 
terminated. 

JSLEV, PSLEV and SSLEV 

These three fields are used to control what level of statistics is to be 


reported to the user when at jobend (JSLEV), a proprietary processor is 
invoked (PSLEV) or at jobstep (SSLEV). 
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MODE 

This field specifies the mode in which the user js running: M_INT# 
Cinteractive, online), M_BATCH# (batch), M_GHOST# (ghost) or M_TP# 
(transaction processing). 


NEXTCC 


This specifies the source of the next command stream read. 


User Parameters for M$YC 


In general, a command processor is not granted access to memory belonging to a 
user program. However, if the command processor is being entered as a result 
of an M$YC monitor service request, the monitor executes LTRAS to invoke the 
command processor, making the user's M$YC parameters available through the 
command processor's Parameter Stack. 


Parameter 0 - frames the command which may consist of a TEXT string of up to 
256 characters. The “bound” of this parameter (byte count - 1) 
is stored in BSJIT.YCOSZ. 


Parameter 1 - frames the V area of the MSYC FPT. Bit O jis set if ECHO = YES 
was specified. Bit 1 is set if NOERR = YES was specified. 


The pointers to these parameters are defined in the module B_USRPTRS_D. These 
pointers are SYMDEFed as BSPSOS and B$PS1$. 


Exit from a Command Processor 

The Command Processor communicates the action to be taken for this user via 
the various options of M$CPEXIT. This monitor service is used to: 

e Initiate execution of a user program or shared processor. 


e Resume execution of an interrupted program (following Control-Y or an M$YC 
service call). 


e Associate a debugger with a (possibly interrupted) user program. 

e Remove a user from the system. 

Before a Command Processor issues an M$CPEXIT, it must close and release 
(M$RELDCB) all its DCBs and, in general, clean up. Data Segments obtained via 
M$GDS are released unless CP_KEEPDS# is set in BSJIT.CPFLAGS1. 


The MSCPEXIT monitor service and its options are explained in the CP-6 Monitor 
Services Reference Manual, Section 8. 


Guidelines for Debuggers 


A debugger can be used to monitor and/or control the execution of a program in 
the user domain. 


Entry to the Debugger 


The debugger is entered under any of the following conditions: 
1. Initial entry to the debugger: 


a. A program is started under the debugger. 

b. The debugger is invoked at Job-Step with no run unit associated. 

c. The debugger is invoked after a user program is in execution by 
striking Control-Y and asking for the debugger. 


2. An overlay of the user's program is loaded. 


3. A program is put into execution via M$LINK or MSLDTRC or an MSLINKed to 
program is restored. 


4&4. An Exceptional Condition occurs other than: 


a. Line hang-up 
b. Operator !X key-in 
c. Bad call, and the user specified ALTRET. 


5. A user is exiting an Exceptional Condition processing procedure. 


6. The debugger is associated via an M$ALIB Service Request. If the program 
making the request jis not executing under control of the debugger (see 
Item 1), DELTA is thereafter entered only on subsequent M$ALIB requests or 
for requests to be put under control of the debugger. Note that this may 
or may not be the initial entry to the debugger. 


When the debugger is entered a standard Exceptional Condition frame containing 
a copy of the user's Safe-Store frame js placed in the debugger's TCB. The 
Exceptional Condition Code (BSEXCFR.ECC), Sub-code (BSEXCFR.SUBC) and Event ID 
(BSEXCFR.EVID) uniquely identify the condition that caused the entry to the 
debugger. The %SUB_EXC and %SUB_ECCDELTA macros from the system macro Library 
provide string substitutions for the values of these fields as indicated in 
Tables 11-1 and 11-2. 
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Table 11-1. ECCs for Debugger 


Reason for Entry 


ECC_DELTA# 


SC_STARTU# User program started under the debugger. 


SC_JOBSTEPA 


Debugger was invoked at Job-Step time. 
No Run unit associated. 


SC_YC# Post association of the debugger while 


the user program is in execution. 
BSEXCFR.EVID contains one of 
the following values: 

EVID_USERA 
EVID AUTOS# 


ECC_OLAY# Contains the Overlay has been loaded. 


Node# BSEXCFR.LEVID contains one of 
the following values from the 
MSOLAY FPT: 


EVID _CANCEL# 
EVID _ENTERA 
EVID _NOPATH# 


ECC_LINK# SC_MLINK# User program entered via MSLINK. 


SC_MLDTRC# User program entered via M$LDTRC. 


ECC _LRTN# . MSLINKed to program has been 
restored. 


ECC ALIB# - Debugger was invoked via MSALIB. 
BSALIBCF].CMDSZ contains the byte 
size of the command. 
BSALIBCFIJ.REPLYSZ contains the 
byte size of the reply area. 
BSALIBCFJ.WHO is set as follows: 


SC_AUSR# User Program 
SC_AASL# - Alternate Shared Library 
SC_ASHR# - Standard Shared Processor 
SC_EXUO# Execute-only Run unit 


ECC_EXCRITN# Exit from a user's exceptional 
Condition procedure. BSEXCFR.EVID 
contains the address of the call. 


SC_TRIN# MSTRIN 


SC_MERC# MSMERC 

SC_MERCS# MSMERCS 

SC_RETRY# MSRETRY 

SC_RETRYS# MSRETRYS 

SC_XCONXIT# Final Exit from Exit Control. In 


this case BSEXCRTN.TYP has the 
following values: 


XCON_EXIT# - MSEXIT 
XCON ERR# - MSERR 
XCON XXX# - MSXXX 


ECC DBRK# = Data Break Point 
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ECC _TIMER# 


ECC_EVENT# 


ECC_INT# 


ECC_XCONA 


ECC_PMME# 


ECC_ARITH# 


ECC_PROG# 


ECC_ERROR# 


When the debugger 


Table 11-2. 


As specified 
by user 


SC_BRK# 


SC_BYC# 


See CE33 
Section 6 


See CE33 
Section 6 


See CE33 
Section 6 


See CE33 
Section 6 


See CE33 
Section 6 


ECCs for User Exceptional Condition 


Reason for Entry 
MSSTIMER specified interval 
expired. 


Event over which the user has 
requested control occurred. 


Time-sharing terminal break key. 

The debugger request from the Command 
Processor when the debugger is already 
associated. 


User exit condition, normal 
or abnormal. 


Error on Monitor Service request. 
No ALTRET specified on user's call. 


User caused an Arithmetic 
fault. 


User caused a Programmed 
fault. 


User caused an Error class 
fault. 


is entered because of a user's Exceptional Condition, the 


ECC and the remainder of the frame reflects what would have been placed on the 
user's TCB had the user not been running under the debugger and had 


established control of the specific condition. 
user specified Exceptional Condition control requests. 
Condition frame 


MSDRTN FPT. 


Word 1 of the TCB frame is non-zero if the ASL was 
the debugger. 
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No determination is made as to 
The Exceptional 


is moved to the user's TCB and the procedure to handle the 
condition is entered only when this action is specified via options of the 


(Refer to the description of the SETECC and ECC options below.) 


jn control upon entry to 


Note that this can happen only if the user has hit Break and 
the ASL has not requested break control or if the user has hit Control-Y and 
invoked the debugger while the ASL is in control. 


Entry to the Debugger 
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Debugger Capabilities 


The power of the debugger comes from its position of control between the 
monitor and the user program for all exceptional conditions. The special 
privileges afforded a debugger are: 


e the ability to set the data breakpoint software flag in the user's page 
table. See MS$SSC in Section 8 of the Monitor Services Reference Manual. 


e the ability to write on user Instruction Segment and user dynamic data 
segment pages. 


e the ability to use the MSORTN monitor service 
e the ability to issue an M$SCREECH monitor service request 


e the ability to issue an MSXCONRTN monitor service request. 


DCBs for Debugger 


The DCB Table entry for DCB 9 is reserved for use by the debugger. This DCB 
should be referred to as M$DELT#; its EQU is in CP_6 SUBS.:LIBRARY. Any other 
DCBs used are not protected from use by the user program. 


Addressing User Memory from Debugger 


The debugger has access to the user's Working Space through descriptors stored 
in the Special Descriptor Access descriptor slots in the debugger's Linkage 
Segment. The following pointers (which are DEFed in B_USRPTRS_D) may be used 
to access the user's area: 


BSSPCL1$ -> the user's Safe-Store frame 
BSSPCL2$ -> the user's Linkage Segment 
BSSPCL3$ -> the user's Argument Segment 
BSSPCL4$ -> the user's Parameter Segment 
BSSPCLS$ -> the user's Instruction Segment 


The first four of these descriptors are type 1; the user's Instruction Segment 
descriptor is type 0. The Special Access Descriptors 2 through 5 are a copy 
of those from the user's Safe-Store frame. Unless the debugger is being 
entered as a result of an M$ALIB from an ASL, shared processor or execute-only 
run unit, the Page Table write control bit for procedure pages in the user's 
ISR is set prior to entry to the debugger; it is reset when the debugger 
returns to the monitor via MSORTN. 


The monitor normally enters the debugger via the LTRAD instruction. However, 
if the debugger is being entered as a result of an M$ALIB request, the monitor 
executes LTRAS to invoke the debugger making the user's MS$ALIB FPT available 
through the debugger's Parameter Stack: 


Descriptor 
Descriptor 
Descriptor 
Descriptor 


- frames the Debugger name. 

- frames the area containing the command. 

- frames the area where the debugger may return a reply. 

- frames the V area of the M$ALIB FPT. FPTSALIB_V may be used to 
define the based structure of this area. 


WN Oo 


The pointers to these parameters are defined in the module B_USRPTRS_D and are 
SYMDEFed as BS$PSO$, BSPS1$, BSPS2$ and BSPS3$. 
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Ten words of user data space are set aside for use by debuggers. These words 
are inserted by the Linker and are found by a pointer which is Located in the 
second word of the user's first procedure page. The sixth through tenth words 
of this space are reserved for use by XDELTA. 


Data Breakpoints 


A debugger may use the M$SSC service to cause a data breakpoint flag to be set 
for specified page(s) owned by the user (see M$SSC in the Monitor Services 
Reference Manual, Section 8). 


Once this flag is set, the monitor causes the debugger to be entered if the 
user causes a fault because of trying to modify data on a page for which this 
flag is set. ECC is set to ECC _DBRK# in the TCB frame upon entry to the 
debugger. The debugger can cause the data breakpoint flag to be reset by 
again using the M$SSC service or by the MSDRTN DBRK option (see MSDRTN in the 
Monitor Services Reference Manual, Section 8). 


Exit from a Debugger 


The debugger returns control to the user program via the MSDRTN service 
request. This monitor service is used to: 


e Change the registers and/or IC of the user program 
e Resume execution of the user program 
e Terminate execution of the user program 


e ALTRET to the user's M$ALIB monitor service request 
e Disassociate the debugger from the user program 


The MSDRTN monitor service and its options are explained in the CP-6 Monitor 
Services Reference Manual, Section 8. 
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Guidelines for Alternate Shared Libraries 


An Alternate Shared Library CASL) is a special shared processor that can be 
called directly from the user program via the CLIMB instruction. Its primary 
use is for the implementation of a data base manager; it may also be used to 
implement other applications such as 1/0 graphics packages, etc. 


Associating an ASL with the User 


An ASL is associated with a user whenever that user begins execution of a run 
unit that has an ASL specified in the HEAD record or when the ASL is the 
object of an M$ALIB monitor service request. 


There are two methods of associating an ASL with a user run unit. One method 
is to automatically associate it when the run unit is invoked. This happens 
if the head record of the run unit contains an ASL name. The head record 
contains an ASL name if either the ALTSHARELIB option is specified in the Link 
of the run unit, or one of the object unit head records that comprise the run 
unit contains an ASL name (COBOL associates I-D-S/II by using the latter 
method). In either case, the LINKer uses the ASL to satisfy the references to 
the symbols that correspond to the function being provided by the ASL. 


An ASL may also be associated dynamically at run-time by a user program that 
issues a call to the M$ALIB monitor service. In this case the ASL is not 
present until the M$ALIB is issued; no ALTSHARELIB on the LINK command or ASL 
name in the head record is necessary. Instead the ASL should be included in 
the LINK command as if it were a normal object unit. This causes the LINKer 
to satisfy references to the functional entry points of the ASL run unit 
without forcing it to be automatically associated. 


Defining the Function Codes of the ASL 


The creator of the ASL must define symbolic function names to distinguish the 
various operations the ASL performs. This is necessary since there is only 
one actual entry point into the ASL. The symbols used to identify the 
functions are defined in a module, SYMDEFed, and that module is linked as part 
of the ASL. 


Because it is the symbolic values that define the functions, and not the 
contents of the memory locations associated with the symbols, the symbols are 
usually equated to specific sequential constants in a BMAP routine. 


For example, for an ASL capable of performing function "X" and function "Y", 
the BMAP module contains: 


SYMDEF ASLSFUNCTION X 
SYMDEF ASLSFUNCTION Y 


ASLSFUNCTION X EQu 2 
ASLSFUNCTION_Y EQuU 3 


Note that the value of 1 is skipped. This is because the value of 1 is 
reserved to indicate ASL recovery and should only be used for that function. 
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User Calls to an ASL 


The CP-6 Operating System provides a CLIMB instruction interface for 
communication between the user and an associated Alternate Shared Library. A 
slot has been reserved in every user's Linkage Segment for the ASL Entry 
Descriptor. The descriptor is built from information contained in the ASL run 
unit. When a user program wishes to cause entry to an ASL, it issues a CLIMB 
instruction in which the S,D field is coded to reference the Linkage Segment 
descriptor that points to the ASL. 


This CLIMB instruction is generated by the PL6 compiler when the user calls a 
procedure that is defined using the CONV type 2 attribute of the ENTRY 
declaration. 


If no parameters are to be passed: 


DCL asl_function_name ENTRY CONV(2,0) 
CALL asl_function_name; 


If parameters are to be passed: 


DCL asl_function_name ENTRY(1) CONV(2,codel) 
CALL asl_function_nameCasl_ vector list); 


where: 
code1 = the number of parameters to be passed. 


The "asl_function_name" is placed in the object unit as a SYMREF rather than 
an ENTREF. The SYMREF is satisfied by the LINKer from the ASL associated with 
the run unit as described above. This is the function code that is passed 
from the user program to the ASL in the XO register. 


The “asl_vector_List™ contains a vector framing each parameter that is to be 
passed to the ASL. This is similar to the FPT passed to the monitor on a 
monitor service request. 


For more information on the descriptors, parameter stacks, and CLIMB 
instructions, see DPS 8 Assembly Instructions reference manual (DHO3). 


A user program that calls an Alternate Shared Library relinquishes control 
until the Library returns control to the user. User-established break 
control, timer run-out, and event reporting are deferred until the ASL returns 
control to the user program. 
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Building an ASL System File 


A programmer who is creating an ASL should provide other users with an INCLUDE 
file that contains the ENTRY declarations for each service the ASL performs. 
This INCLUDE file could also contain macros to generate the vector lists for 
those services that require parameters. 


As explained above the INCLUDE file contains the DCLs that correspond to the 
symbolic function codes for the ASL entry points: 


DCL ASLSFUNCTION X ENTRY CONV(2,0); 
DCL ASLSFUNCTION Y ENTRY CONV(2,3); 


These declare statements define the two ASL functions and indicate that they 
require zero and three vectors respectively. 


The macros to generate the vector list for the ASL functions can be built in 
the same manner as those contained in the CP_6 system file. That is, the 
structure for each function contains a List of vectors followed by a level 2 
sub~structure that is framed by the first vector in the structure. The level 
2 sub-structure contains the additional parameters necessary for the function. 
This whole structure is generated within a MACRO that can specify default 
options and parameters. An example of ASLSFUNCTION _Y is as follows: 


XMACRO ASLSVECTORS_ YCNAME=ASLSVECTORS Y, 
OPTIONICYES='1'B,NO='0'B)='1'B, 
OPTION2 (RED=1, ORANGE=2, YELLOW=3,GREEN=4,BLUE=5, INDIGO=6,VIOLET=7)=0, 
INPUT=NIL, 
OUTPUT=NIL); 
DCL 1 NAME STATIC, 
2 V_ VECTOR INITCVECTOR(CNAME.V)), 
2 INPUT_ VECTOR INITCADDRCINPUT)), 
2 OUTPUT VECTOR INITCVECTORCOUTPUT)), 
2 V DALIGNED, 
3 OPTION1T# BIT(1) INITCOPTION1) UNAL, 
3 OPTION2# UBIN(3) INITCOPTIONT2) UNAL; 
“4MEND; 


The user who then wishes to access the ASL builds a program that contains the 
following statements: 


A; PROC MAIN; 
RINCLUDE ASLSSYSTEM FILE 
ZASLSVECTORS YCNAME=FUNCTION Y,INPUT=IN,OUTPUT=OUT,OPTIONI=YES); 


DCL IN CHAR(15) STATIC INITC"HeLlo there ASL"); 
DCL OUT CHAR(15) STATIC; 


CALL ASLSFUNCTION YCASLSVECTORS_Y); 
END A; 
Refer to the CP-6 PL-6 Reference Manual (CE44), Section 10 for details on the 


CONV attribute and Section 12 for MACRO definition. Calls from other 
languages could be done through a BMAP interface. 
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Entry to ASL 


The main routine of the ASL should be a BMAP routine. This is necessitated by 
two facts. First, the function code associated with this call is placed in 
Register XO by the CLIMB instruction. Second, the BMAP routine has to 
determine whether the ASL has been entered before or not and set up an AUTO 
Stack as described earlier in this section. 


The routine makes use of an initialized data segment. Any segment besides 
AUTO may be used. The following example uses Dynamic segment 8. Thus the 
BMAP routine assumes the following PL-6 declarations are part of the ASL code: 


DCL 1 ASL_STATUS STATIC AREADEFC(DS8SID) ALIGNED, 
2 INITED UBIN WORD INIT(O), 
2 BREAK UBIN WORD INIT(O); 
DCL 1 ASL_STATUSS PTR CONSTANT SYMDEF INITCADDRCASL_STATUS)); 


The entry module for the example program would be coded as follows: 


* 
ENTDEF ASLSENTRY The ASL start address is ASLSENTRY 
* 
* Define the symbols that correspond the the functions 
* supported by the Alternate Shared Library 
* 
SYMDEF ASLSRECOVERY 
SYMDEF ASLSFUNCTION X 
SYMDEF ASLSFUNCTION Y 
* 
ASLSRECOVERY EQU 1 
ASLSFUNCTION X EQU 2 
ASLSFUNCTION Y EQU 3 
* 
* References to the ASL subroutines written in PL-6 
* 
ENTREF ASLSINIT 
ENTREF ASLSRECOVERY 
ENTREF ASLSROUTINE X 
ENTREF ASLSROUTINE Y 
* 
ENTREF X66_MSTATIC and external BMAP routines 
* 
* References to external segments 
* 
SYMREF BS$PIA$ We will Link with B_USRPTRS_D 
SYMREF BSAUTOS 
SYMREF BSIS$ 
* 
* References to the AREADEF structure. 
* 
SYMREF ASL_STATUSS 
INITED EQU 0 
BREAK EQU 1 
* 
* CP-6 monitor service macros 
* 
ALTRETFLG BOOL 400000 
INTRTN EQU 17 
XXX EQU 3 
* 
MSINTRIN MACRO 
* This macro generates a monitor service call that returns 
* control to the user domain just as if the normal ASL 
* return were issued. In addition it causes the operating 
* System to cause a BREAK event to be reported on the 
* user. Thus the ASL can transfer breaks it receives 
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to the user program when it is ready. 


PMME T7+ALTRETFLG 
ENDM 
MSXXX MACRO 
t This macro generates a standard M$XXX. 
PMME XXX 
ENDM 
x 
ASLSENTRY NULL 
EAX7 0,0 Copy function code to X7 
TMOZ BADFCN If legal codes are all positive 
CMPX7 ASLSFUNCTION Y Highest defined function code 
TPL BADFCN Out of range 
LDI =04010 Set HEX and OVRFL mask 
* 
x See if this is the initial entry 
* 
LDP? ASL_STATUSS$ Pointer to AREADEF structure 
LDA INITED,,7 Have we been entered before 
TNZ SETAUTO Yes 
LDA 1,0L Indicate have been entered 
STA INITED,,7 And save 
* 
* Initialize an AUTO stack 
x 
TSxO X66_MSTATIC 
ZERO 0,0 
* 
* Call any ASL initialization routines. 
* 
TSX1 ASLSINIT 
ZERO 0,0 
TRA FUNCTION 
* 
* Set PR2 to current top of auto stack 
* 
SETAUTO LDP2 BSAUTOS Make sure base pointer set up. 
LXL2 0,,2 Offset to top AUTO frame 
SWDX 1,2,2 Compute pointer to top. 
* 
* Now go do the requested function 
* 
FUNCTION LDX1 CHKBREAK, DU For PL-6 returns 
TRA *+1,7 
TRA BADFCN 0 is not used in this example 
TRA ASLSRECOVERY 1 is reserved for recovery 
TRA ASLSROUTINE X 
TRA ASLSROUTINE Y 
x 
* RET is the common exit point 
* 
* It is the ASL's responsibility to save BREAK events received 
* when it is in control and report them to the user. The 
x ASL must set up an ASYNC routine to intercept breaks, and 
* must set the flag STATUS.BREAK to be non-zero. This 
* interface will check that flag and report the break event 
* to the user if it is set. 
* 
CHKBREAK NULL 
INHIB ON 
LOP? ASL_STATUS$ Set pointer to status block 
LDA BREAK,,7 Check for break during ASL 
TZE RET None. Normal return 
« 
* Break hit during ASL execution. Report event to user. 
LDA 0,0L Clear old flag 
STA BREAK,,7 
CE62-00 Entry to ASL 


11-26 


MSINTRTN 


* 
RET NOP 
EXIT 
INHIB OFF 
* 
* Issue MSXXX if the user passes a bad function code 
* 
BADFCN MSXXX 
END ASLSENTRY 
ASL Capabilities 


An ASL has the following special abilities: 


e the ability to access the *I file 

e the ability to issue an MS$SCREECH monitor service request 
e the ability to issue an MSXCONRTN monitor service request 
e the ability to issue an MSINTRITN monitor service request. 


DCBs for ASL 


There are no special DCBs for ASLS. However, an ASL may use the DCBs defined 
by the user, or acquire his own DCBs using the M$GETDCB monitor service. The 
XONLY option can be used to disallow user programs from accessing the ASL's 
DCBs. See the discussion of MS$OPEN in the Monitor Services Reference Manual 
for details. 


Addressing User Memory from ASL 


Each parameter passed by the call to the ASL corresponds to a vector specified 
as part of the user's call. When the ASL is entered, the hardware builds a 
descriptor on the parameter stack associated with each of these vectors. Thus 
to access the first parameter, the ASL uses a pointer with the SEGID 
referencing parameter stack entry zero. The pointers for up to nine 
parameters are defined in the module B_USRPTRS D. These pointers are SYMDEFed 
as BS$PSO$S$, BSPS1$, BSPS2$ ... BSPS8S. 


Thus in the example above, to access the memory framed by 

ASLSVECTORS Y.INPUT_, BSPS1$ would be used. To access 

ASLSVECTORS Y.V.~OPTIONS1, BSPSO$ would be used. In the second case a 
structure must exist that defines the V area of the ASLSVECTORS Y structure, 
without the additional vectors. (The pointer BSPSO$ will point to 
ASLSVECTORS Y.V; using this pointer in combination with the ASLSVECTORS 
structure will not work). This can be automatically generated by the X 
account tool FPTCON which converts the V areas of FPT-lLike structures for use 
after a CLIMB has been issued. 


If the creator of an ASL defines functions that require more than nine 
parameters, pointers to these parameters may be built as follows: 


DCL BSPS9 UBIN CONSTANT INIT(9); 
DCL BSPS9S REDEF BSPSI PTR; 


CE62-00 Addressing User Memory from ASL 11-27 


Exit from an ASL 


When the ASL has completed its functions, it must return to the user. This is 
done by performing an outward CLIMB, which restores the user environment and 
returns control to the user program. Note that this is done in the example 
above. When the PL-~6 routine ASLSROUTINE_X or ASLSROUTINE_Y simply returns, 


control transfers to "RET' in the setup routine which performs the outward 
CLIMB. 


ASL Recovery 


The key to ASL recovery is the *I file. This file can only be accessed from 
the ASL's domain. The existence of the *I file causes GHOST1 to associate and 
call the ASL during the recovery procedure with a function code of 1. It is 
the ASL's responsibility to write records to the *I that are useful during the 
recovery process. As an example, I-D-S/II writes before-images of updates to 
the *I and uses them to back out of partial updates if a deadlock, abort or 
recovery occurs. 


As part of the recovery process, the JIT for each user is written to the dump 
area of the system disk. After the system has re-booted itself, the system 
ghost, GHOST1, is entered where further recovery functions are performed. One 
of these functions is to access the user JITs from the dump area to determine 
if ASL recovery entry is indicated. 


If the disk address of the FIT for the *I file in the user's JIT is non-zero, 
that address is moved to the *I entry of GHOST1's BSJIT.STAR.DA and the file 
is opened (test mode) in order to locate the FPARAMS. The PROCATTR 
information in the FPARAM table Cif any) is assumed to contain the TEXTC name 
of the ASL that was associated with the user at the time of the Screech. 


This name is then used as the NAME parameter of an M$ALIB request. If the ASL 
has been established as a Special Shared Processor via the SPROC command to 
TIGR, the ASL is now associated with GHOST1. 


GHOST1 then causes entry to the ASL via the CLIMB instruction. No parameters 
are passed; x0 is set to 1. The routine to handle recovery must, therefore, 
correspond to a function code of 1. At this point the ASL may do whatever is 
required for closing the data base. 
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Debugging an ASL 


An ASL may be debugged using XDELTA as described earlier in this section. 
However, since the interface between the user program and an ASL is through 
the hardware CLIMB interface and not through the monitor, considerable 
debugging may be accomplished by Linking the ASL object units and the user 
program object units into one run-unit and using DELTA to debug. 


The modules that make up the ASL may be Linked with the modules of the user 
program that calls that ASL to form a single run-unit that is to be executed 
in the user domain under DELTA. The calls from the user program to the ASL 
need to be changed from the inter-domain CLIMB via the ASL entry descriptor to 
an intra-domain CLIMB through the user's Instruction Segment descriptor. The 
difference between an inter-domain CLIMB and an intra-domain CLIMB is as 
follows. The IC is loaded from the 18-bit entry location contained in the 
Entry descriptor if the CLIMB is inter-domain, and from the address field of 
the CLIMB instruction if intra-domain. 


In order to make an intra-domain call to an ASL, the actual CLIMB instruction 
must be coded in BMAP. Because of this fact, the PL-6 routines that call an 
ASL must be modified to call a BMAP interface module which will then issue the 
intra-domain CLIMB instruction. 


In order to facilitate switching from an inter-domain interface to an 
intra-domain interface, it is recommended that all the calls to the ASL be 
issued from a BMAP module. That is, the ASL system file would contain the 
macros to generate the vector lists, and ENTRY declarations for the BMAP 
routine names for each function of the ASL. The BMAP routine names cannot be 
the same as the ASL function names although they should be similar enough to 
identify the functions they represent. The ASL system file would then 
contain: 


MMACRO ASLSVECTORS XC ... 


%MEND; 
*MACRO ASLSVECTORS YC ... 


%MEND; 
DCL ASFUNCTION X ENTRY(1); 
DCL ASFUNCTION Y ENTRY(1); 


The PL-6 routine wishing to call the ASL contains statements as follows: 


ZINCLUDE ASLSSYSTEM FILE; 
ZASLSVECTORS X; 


CALL ASFUNCTION XCASLSVECTORS X); 
CALL ASFUNCTION_Y; 


The BMAP routine then issues the CLIMB to the ASL. It is a simple matter to 
code the BMAP routine to issue both types of the CLIMB instruction depending 
on a patch being applied. Thus only one version of the interface is necessary 
to user either a real production ASL or a debug version. 


Once the type of ASL has been decided upon and called, it is no longer valid 
to switch types. That is, if an inter-domain call is issued to the ASL, jit is 
not valid to modify the BMAP interface to start issuing intra-domain calls and 
vice versa. The reason is that the two different types will actually call two 
different instances of the ASL Cone that is a real ASL and one that is Linked 
jnto the user's run unit). 


The following is an example of a BMAP interface routine. This routine is 
coded to issue the inter-domain CLIMB by default. If the instruction at DEBUG 
is modified to a NOP, the routine issues intra-domain CLIMBs. (Of course jit 


js also necessary to LINK the ASL code into the run unit as mentioned 


previously, for the intra-domain CLIMB to work). 
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* 


Define the entry points to this routine 
ENTDOEF ASRECOVERY 

ENTDEF ASFUNCTION X 

ENTDEF ASFUNCTION Y 

Define patchable location for ease of access 
ENTDEF DEBUG 

Reference the ASL function codes 

SYMREF ASLSRECOVERY 

SYMREF ASLSFUNCTION X 

SYMREF ASLSFUNCTION Y 


Reference to the ASL main entry point 


* 
ENTREF ASLSENTRY 
* 
* Other external references that are required 
* 
ENTREF X66 AUTO 1 Auto references 
ENTREF X66 ARET 
SYMREF BSAUTOS 
SEGREF ISSID For intra-domain CLIMB 
SEGREF ASLENTSID For inter-domain CLIMB 
* 
* Now the actual code 
x 
ASRECOVERY NULL 
TSXO X66 AUTO 0 Set up O parameters 
ZERO 4,0 
LDXxO ASLSRECOVERY, DU Put function code in x0 
LDX1 0,DU Set for no vectors 
TRA DEBUG 
ASFUNCTION X NULL 
TSXxO X66 AUTO 1 Set up 1 parameter 
ZERO 4,1 
LDXO ASLSFUNCTION X,DU Put function code in x0 
LoPO 0 PRO now points to the vectors 
LDXx1 3,DU Set for 3 vectors 
TRA DEBUG Go issue the CLIMB 
ASFUNCTION Y NULL 
TSxO X66_ AUTO 0 Set up 0 parameters 
ZERO 4,1 
LDXO ASLSFUNCTION Y,DU Put function code in x0 
LDX1 0,DU Set for no vectors 
TRA DEBUG 
DEBUG TRA INTER,1 Default to issue inter-domain 
TRA INTRA, 1 Issue intra-domain CLIMB 
INTRA TRA INTRAO Intra-domain. Zero vectors. 
TRA INTRA1 Intra-domain. One vector. 
TRA INTRA2 Intra-domain. Two vectors. 
TRA INTRA3 Three vectors. 
* 
* The ENTER generates a CLIMB instruction. Since an entry 
* descriptor is not being used in the intra-domain version, 
* the ASL entry point must be specified. The XO indicates 
* that the function code is already in x0 and should not 
* be modified. 
* 
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INTRAO ENTER ISSID,0, CASLSENTRY,0) 


TRA FIXAUTO 
INTRA1 ENTER ISSID,1,CASLSENTRY,0) 
TRA FIXAUTO 
INTRA2 ENTER ISSID,2, CASLSENTRY,0) 
TRA FIXAUTO 
INTRAS3 ENTER ISSID,3, CASLSENTRY,0) 
TRA FIXAUTO 
* 
* An intra-domain climb destroys the SEGIDs of all the 
* pointers in the pointer registers. Since PL-6 assumes 
* that PR2 always points to the top of auto, it is necessary 
* to restore PR2 before returning. 
FIXAUTO LODP2 BSAUTOS Pointer to the beginning of AUTO 
LXL2 0,,2 Negative current size. 
SWDX 12,2 Reset PR2 to correct value 
TRA RETURN 
* 
* The ENTER generates a CLIMB instruction. The symbol 
* ASLENTSID references an entry descriptor that describes 
* the ASL and already contains the start address of the ASL. 
* The ENTER therefore does not specify the ASL entry point. 
* Again, X0 indicates that the function code is already 
* in x0. 
* 
INTERO ENTER ASLENTSID,0, (0,0) 
TRA RETURN 
INTER1 ENTER ASLENTSID,1,(0,0) 
TRA RETURN 
INTER2 ENTER ASLENTSID,2,(0,0) 
TRA RETURN 
INTER3 ENTER ASLENTSID,3,(0,0) 
TRA RETURN 
* 
RETURN TSx2 X66_ARET 
*« 
END 


The ASL entry module must also be changed to recognize the different 
conditions under which the ASL might be called. In the case of an 
intra-domain CLIMB the ASL should use the existing AUTO segment instead of 
jnitializing its own. In addition it is sometimes useful to know within the 
ASL if it has been called by an inter-domain or intra-domain CLIMB. 


To facilitate the latter case, a field can be defined in the structure 
ASL_STATUS as follows: 


DCL 1 ASL_STATUS STATIC AREADEFCDS8DIS), 
2 INITED UBIN WORD INIT(O), 
2 BREAK UBIN WORD INIT(O), 
2 INTRA UBIN WORD INIT(O); 


Where ASL_STATUS.INTRA is non-zero if an intra-domain CLIMB is issued. The 
following is an updated version of this interface: 


& 


ENTDEF ASLSENTRY The ASL start address is ASLSENTRY 
* 
* Define the symbols that correspond the the functions 
* supported by the Alternate Shared Library 
* 
SYMDEF ASLSRECOVERY 
SYMDEF ASLSFUNCTION X 
SYMDEF ASLSFUNCTION_Y 
* 
ASLSRECOVERY Eau 4 
ASLSFUNCTION X EQqu 2 
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ASLSFUNCTION Y EQU 3 
* 


* References to the ASL subroutines written in PL-6 
* 

ENTREF ASLSINIT 

ENTREF ASLSRECOVERY 

ENTREF ASLSROUTINE X 

ENTREF ASLSROUTINE Y 


ENTREF X66 MSTATIC and external BMAP routines 
* 
* References to external segments 
* 
SYMREF BSPIAS We will Link with B_USRPTRS D 
SYMREF BSAUTOS 
SYMREF BSIS$ 
* 
* References to the AREADEF structure. 
* 
SYMREF ASL_STATUSS 
INITED EQU 0 
BREAK EQU 1 
INTRA EQuU 2 
* 
* CP-6 monitor service macros 
* 
ALTRETFLG BOOL 400000 
INTRIN EQU 17 
XXX EQU 3 
* 
MSINTRIN MACRO 


* 


This macro generates a monitor service call that returns 
* control to the user domain just as if the normal ASL 

* return were issued. In addition it causes the operating 
* System to cause a BREAK event to be reported on the 

* user. Thus the ASL can transfer breaks it receives 

x the the user program when it is ready. 


PMME 17+ALTRETFLG 
ENDM 
MSXXX MACRO 
* This macro generates a standard MS$XXX. 
PMME XXX 
ENDM 
* 
ASLSENTRY NULL 
EAX7 0,0 Copy function code to X7 
TMOZ BADFCN If legal codes are all positive 
CMPX7 ASLSFUNCTION Y Highest defined function code 
TPL BADFCN Out of range 
LDI =04010 Set HEX and OVRFL mask 
* 
* See if this is the initial entry 
* 
LDP? ASL_STATUSS Pointer to AREADEF structure 
LDA INITED,,7 Have we been entered before 
TNZ SETAUTO Yes 
LDA 1,0L Indicate have been entered 
STA INITED,,7 And save 
* 
* Check for which type of CLIMB 
* 
LDP 1 BSPIA$ Get pointer to the PIA 
LDP2 BSIS$ Load Instruction Segment pointer 
INHIB ON 
STD2 0,,1 Store the descriptor in the PIA 
LDA 0,,1 Get the Working Space Register # 
INHIB OFF 
C—E62-00 Debugging an ASL 


11-32 


ANA =0160,DL Mask out junk 
ARS 4 Shift into place 
CMPA 6,0L Is it from inter-domain CLIMB 
TZE CKAUTO Yes. Leave flag as is. 
LDA 1,DL Non-zero value 
STA INTRA,,7 Set flag in ASL_STATUS 
x 
CKAUTO LDOP2 BSAUTOS 
INHIB ON 
STD2 0,,1 Store AUTO descriptor in the PIA 
LXL1 0,,1 Load the descriptor access flags 
INHIB OFF 
LXL1 0,,1 Load the descriptor access flags 
ANX1 =0100600,DU Test Read, Not empty, Present 
ERX1 =0100600, DU 
TNZ NOAUTO None yet. Initialize one. 
* Use existing AUTO segment 
LXL2 0,,2 Offset to top AUTO frame 
SWDX Teepe Compute pointer to top. 
TRA INIT 
* 
* Initialize an AUTO stack 
* 
NOAUTO TSXO X66 MSTATIC 
ZERO 0,0 
* 
* Call any ASL initialization routines 
* 
INIT TSx1 ASLSINIT 
ZERO 0,0 
TRA FUNCTION 
* 
* Set PR2 to current top of auto stack 
* 
SETAUTO LDP2 BSAUTOS Make sure base pointer set up. 
LXLe 0,,2 Offset to top AUTO frame 
SWDX 1,2,2 Compute pointer to top. 
* 
* Now go do the requested function 
* 
FUNCTION LDX1 CHKBREAK, DU For PL-6 returns 
TRA *+1,7 
TRA BADFCN 0 is not used in this example 
TRA ASLSRECOVERY 1 is reserved for recovery 
TRA ASLSROUTINE X 
TRA ASLSROUTINE_Y 
* 
* RET is the common exit point 
* 
* It is the ASL's responsibility to save BREAK events received 
* when it is in control and report them to the user. The 
* ASL must set up an ASYNC routine to intercept breaks, and 
* must set the flag STATUS.BREAK to be non-zero. This 
* interface will check that flag and report the break event 
* to the user if it is set. 
* 
CHKBREAK NULL 
INHIB ON 
LDP7 ASL STATUS$ Set pointer to status block 
LDA BREAK,,7 Check for break during ASL 
TZE RET None. Normal return 
* 
* Break hit during ASL execution. Report event to user. 
LDA 0,DL Clear old flag 
STA BREAK,,7 
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MSINTRITN 


RET NOP 
EXIT 
INHIB OFF 
x 
* Issue MS$XXX if the user passes a bad function code 
3 
BADFCN MSXXX 
END ASLSENTRY 


Linking an ASL 


Once coded an ASL must be Linked. The following command illustrates Linking 
of a production ASL: 


'LINK ; 
B_SSPSL_D.:LIBRARY,; 
ASLSENTRY,; 
ASLSPLO6$SUBROUTINES,; 
B_USRPTRS_D.:LIBRARY,; 
X6USCSEQU.:LIBRARY ; 
OVER ASL_LIVE CASLIB,NOSHARELIB) 


The ASL then needs to be installed in memory. This can be done on a temporary 
basis using the INSTALL command under the SPIDER processor, and on a permanent 
basis using TIGR as mentioned above. 


The user program is Linked using the command: 


'LINK ; 
USRSMODULE,; 
ASLSBMAP_INTERFACE 
OVER USR_PROGRAMCALTSHARELIB=ASL LIVE) 


To Link a debug version of the ASL and user program that issues the 
intra-domain climbs, only one Link is necessary as illustrated by the 
following command: 


1 LINK , 

USRSMODULE,; 
ASLSBMAP_INTERFACE,; 
B_SSPSL_D.:LIBRARY,; 
ASLSENTRY,; 
ASLSPL6SSUBROUTINES,; 

B_USRPTRS D.:LIBRARY,; 

OVER USR PROGRAM DEBUG (NOALT) 


This Link produces a warning that indicates the presence of multiple start 
addresses for the run unit. This is caused by the fact that both the user's 
module USRS$MODULE and the ASL module ASLSENTRY are main procedures. This 
warning can be ignored. Referencing the user's module first in the LINK 
command causes the run unit to start execution at its main procedure and not 
the ASL'‘s. 


The following RUM can then be applied to change the CLIMB to the the 
intra-domain type: 


‘RUM USR_PROGRAM_DEBUG 


M DEBUG NOP 0 
END 
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If the RUM is not applied and the program is executed, an IPR fault occurs 
because the user program tries to issue an inter-domain CLIMB to an ASL that 
is not associated with the run unit. 
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Section 12 


Run-Time Libraries 


Shared Libraries 


A shared library is an executable image of a set of shareable sub-programs 
which is installed in the :SYS account and is permanently memory resident. A 
shared library is constructed by LINK in two parts: shareable procedure and 
static data. The shareable procedure jis always biased at octal 700000 or 
224K. Since a user's instruction segment is Limited to 256K, the procedure 
portion of a shared library is Limited to 32K. The data portion of the shared 
Library is biased at octal 34 and may be as large as is required. When a 
user's program is linked specifying a shared Library Cimplicitly or 
explicitly), the Library static data space is allocated first in the user's 
static data space. ALL other user static data follows the end of the shared 
Library's data space. The total for the procedure and constant data is 
prohibited from exceeding 224K. 


Link Time Association of Shared Libraries 


A shared Library can be associated at Link time by specifying the SHARELIB 
option which causes the specified Library to be associated with the run unit. 
An alternate method is to build an object unit that has the two fields 
BSOUHEAD.LNAMSIZ and BSOUHEAD.LNAM filled in appropriately with the desired 
Library name size and text of the name. In this case the Linker will 
automatically associate the specified library from the :SYS account. If 
multiple library names are specified in the object units making up the 
program, the Linker will associated the Library that has the highest 
precedence. The following is a List of shared Libraries in order by 
precedence Chigh to low): 


:SHARED COMMON - for programs compiled or interpreted by FORTRAN, APL, or 
BASIC 


:SHARED COBOL - for programs compiled by COBOL 
:SHARED RPG - for programs compiled by RPG 


:SHARED_ SYSTEM - for programs compiled by PL6. 
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Run Time Association of Shared Libraries 


When a user's program is Linked with a shared library, the user's run unit 
only contains the space reserved for the library's static data. When the 
library is associated at run time (by either fetch or a M$ALIB monitor 
service), the initialized library data will be copied into the space reserved 
for the library data. At that point, the procedure portion of the shared 
Library will also be mapped in the user's working space. Note that the 
procedure portion of the Library is shared among all users and that each user 
has a copy of the data portion. 


Building Shared Libraries 


In order to build a shared Library the SLIB option must be specified on the 
LINK command. The Linker will then produce a run unit that represents the 
shared Library. Since the shared library is a self-contained entity, all 
external references must be resolved when the library is built. 


Since the shared library is a self-contained entity, the user may only refer 
to the externally known entry points in the Library. This ensures that when 
new versions of the Library are made, the user's program does not need to be 
relinked to interface with the new shared Library. The ability to create an 
invariant interface for the user is made possible with the VECTOR option to 
LINK when the Library is built. This option will cause the Linker to 
automatically build a transfer vector at the beginning of the shared Library. 


The ENTRIES sub-option of the VECTOR option allows the builder of the shared 
Library to specify those entry points that are to be included in the transfer 
vector built by the Linker. Once a transfer vector is built, it must be used 
as the basis for all Libraries built thereafter. 


The Linker performs this task by changing the external entry point name to 
refer to a location in the transfer vector. It then maps the entry point name 
concatenated with an underscore to refer to the original entry point. The 
following example should illustrate the concept of a transfer vector. If a 
routine that is to be included in the library starts as follows: 


ENTDEF ABC 
ABC TSXO X66 AAUTO 


and the following linker options are specified 
VECTORCENTRIES CABC) ) 


a transfer vector will be built as follows: 


ENTDEF ABC 
ENTDEF ABC 

ABC TRA ABC_ 

ABC_ TSXO X66 AAUTO 


The RF option informs the Linker that the specified rununit file is a shared 
library and that the transfer vector in it should be used as the starting 
point in building a new transfer vector. The linker will insure that the 
virtual address of the external entry points does not change which allows a 
new Library to be associated without requiring the users to relink. Any new 
entry points will be added to the end of the transfer vector from the 
previously built library. 
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The REMOVE SYMDEF and the REMOVE ENTDEF commands cause the Linker to build the 
shared Library such that only the legal external entry points (those in the 
transfer vector) will be available when a user Links his program with a shared 
Library. This automatically keeps a user from accidentally referencing either 
a data location or a procedure entry point that is not necessarily invariant 
from one version of the library to the next. Using the above example and 
specifying REMOVE ENTDEF the following represents the resultant library: 


ENTDEF ABC 
ABC TRA ABC_ 
ABC_ ——-TSXO X66_AAUTO 


Subroutines Included in Shared Libraries 


The reason for packaging subroutines into a shared Library is twofold: 
convenience and efficient use of system resources. The convenience can be 
achieved by packaging the subroutines in a LEMUR Library. Thus the principal 
motive for a shared Library is system efficiency. This manifests itself in 
several ways: 


1. Reduced Linking time 

2. Reduced time to fetch a program for execution 

3. Reduced use of memory within a system due to sharing of Library procedure. 
However, it is important to note that any program which has a shared Library 
associated will have all of the static data of the shared library in it. Thus 
subroutines to be included in a shared Library should minimize the amount of 
static data used in order to maximize the benefit of system efficiency. This 
factor should also be considered for purposes of possible use of subroutines 


asynchronously, e.g., by break routines. 


There are several things which cannot be done by subroutines which are to be 
in a shared Library: 


1. Explicit references to DCBs other that MS$UC and M$D0. Others must be 
acquired at execution time. 


2. SYMREFs or ENTREFS to symbols not contained in the shared Library. 
3. SYMDEFs of data to be referenced in programs Linked with the Library. 
4. Use of the AREADEF or AREAREF compile-time data segment is not allowed. 


Also, special attention should be paid to the considerations for DELTA 
vis-a-vis shared Libraries as specified in Section 15. 
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User Installation of Shared Libraries 


A Library may be installed as a shared Library temporarily Cuntil system 
shutdown or crash) via the SPIDER processor. This is done via the INSTALL 
command of SPIDER, using a type designation of LIB. For further information 
on the SPIDER processor, see the System Support Reference Manual (CE41). 


A library may be installed as a shared Library permanently, via the Boot 
process. This is done by including the Library on the Labeled portion of the 
PO tape, via the INCLUDE command of the DEF processor, and by including a MON 
command, in the TIGR commands of the Boot instructions, specifying the fid of 
the Library and having a flag designation of LI. 
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Section 13 


Library Functions 


The term “Library services" refers to a set of utility routines which may be 
used by a PL-6 program to perform common, complex, and/or repetitive tasks in 
a simple, standardized fashion. Most library services are designed to 
simplify the job of getting data into a program (prompting the user, reading 
input, parsing commands, reporting errors, etc.) or getting data out of a 
program (formatting data, writing object units, etc.). These services thus 
provide the PL-6 programmer with the same sort of I/0 capabilities available 
to programmers working in other, applications-~oriented Languages such as 
FORTRAN, COBOL, or PASCAL. Most Library services are used extensively by 
various CP-6 components (e.g. PCL and EDIT) and/or processors (e.g. FORTRAN). 
User-written programs which use these library services can be made to resemble 
familiar CP-6 products, and can take advantage of future enhancements in the 
service routines. 


"Library services" are similar to “monitor services" in many ways, but differ 
in several fundamental respects. For example: 


® Like monitor services, all library services are supported by Honeywell. 
STARS may be submitted against library services, using the subject name 
“SHARED SYSTEM". 


@ Both library and monitor services are accessed via the PL-6 "CALL" 
statement. Neither set of services is directly supported by any other 
CP-6 Language. 


e Library services are treated as standard PL-6 subroutines. Normally, such 
services are accessed from within the standard PL-6 run-time Library known 
as :SHARED SYSTEM; however, a user may wish to actually LINK the service 
routines into a program. 


e Library services can interact with the user's program in complex ways; 
monitor services cannot. For example, many Library service routines 
accept an optional PL-6 EPTR variable, which holds the ENTADDR of an 
error-processing routine written by the user; if an error condition is 
detected by the library service, the error-processing routine will be 
CALLed to perform any appropriate action. 


Library service routines generally have the following characteristics: 


e A copy of each service routine is available in the :SHARED SYSTEM shared 
Library, which is normally associated with each PL-6 program. By using 
this shared copy, the programmer may make full use of the routine's 
capabilities without increasing the size of the program. 


e A copy of each routine is available in the :LIB_ SYSTEM unshared Library. 
This Library is automatically searched (and the necessary routine(s) 
Loaded) if a program contains any FORTRAN or COBOL routines (Cand thus 
requires use of the :SHARED_ COMMON or :SHARED COBOL Libraries). 


e A copy of each routine is available in the :LIBRARY account. These 
unshared copies may be explicitly LINKed into the user's program as 
necessary Cif, for example, it is not desirable to associate or search any 
system library file). 
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e Each library service has a name beginning with the letter "X". Some 
Library services are named "X$servicename" (e.g. X$PARSE); others are 
named "XUx$servicename" (e.g. XUUSREAD, XURSGETCMD). 


e Library service routines are designed to be called from a PL-6 procedure. 
Information is normally passed to/from such routines via PL-6 data 
structures. These data structures may be generated by copying a PL-6 
pre-processor file stored in the :LIBRARY account (by coding an 
appropriate ZINCLUDE statement), and invoking the appropriate %MACRO. 

Library service routines can be classified in three general categories: input 

services, output services, and miscellaneous utility services. For additional 


information on many of these services, see the CP-6 Monitor Services Reference 
Manual, Library Services section. 


Input Services 


Services in this class are used to give the programmer the ability to receive 
data from an external source (timesharing terminal, disk file(s), batch 
command stream, etc.) in an easy, standardized fashion. 


Table 13-1. Input Library Services 
Service Description 


XSPARSE 


A general-purpose recursive-descent parser. 


XURSGETCMD 


Command processing service to fetch a command from the user, 
echo it if necessary, parse it, print diagnostics and error 
messages, give the user HELP information, etc. 


XUUSREAD 


A utility to process source, update, and ZINCLUDE records on 
behalf of a CP-6 compiler. 


XSASFSF 


The "fast sequential file" package. This set of routines may 
be used to read CP-6 keyed and consecutive files tn a strictly 
sequential fashion, at speeds of about twice that of the normal 
MSREAD method. 


XUESEVAL 


A general-purpose "expression evaluation” routine, which may be 
used to evaluate arithmetic expressions within commands, and/or 
to provide an IBEX-Like "pre-processing" capability. 
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Output Services 


Services in this class are designed to provide the PL-6 programmer with a way 


of easily formatting and writing output from a program, in useful and/or 
standardized ways. 


Table 13-2. Output Library Services 


Service Description 


XSFORMAT 


A set of routines which provide the programmer with the ability 
to format and present information in a flexible fashion (not 
unlike that provided by the FORTRAN formatted-write feature). 


XSHELP 


A routine which provides a simplified interface to the monitor 
service MSHELP. Programs which call X$HELP can provide their 


users with access to all of the features of the CP~6 !HELP 
command. 


XSASFSF 


The "fast sequential file” package may be used to write CP-6 
consecutive files, roughly twice as fast as the standard 
MSWRITE method. 


XUOSBUILD 


A set of routines which may be used by compilers and other 
utilities to create a standard CP-6 object unit file, which can 
then serve as input to the LINK process. 
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Miscellaneous Utilities 


Service routines in this class perform useful functions not related to 
input/output. 


Table 13-3. Miscellaneous Library Services 
Service Description 
XSALLOCATE 
A general-purpose routine for managing space within a large 


block of memory. 


XUMSLRU 


A routine which manages a “lLeast-recently used” List. 


XUWSWILDCARD 


A routine to perform general-purpose wildcard pattern matching. 
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Section 14 


Compilers and Language Utilities 


Conventions for Language Processors 


Conventions specifically for language processors are described in this 
subsection. 


Standard Run Unit Invocation Format for Compilers 


Shown following is the standard compiler invocation format of the 
Honeywell-supplied compilers. ALL run unit invocation commands are invoked at 
the IBEX command Level with a command of this format. 


C{ON } J 
C{To } J 
'rununit Csourcel, updateJIC{COVER}CobjectIC, lListoutJICCoptionlist)] 
CCINTO} J 
where 
rununit is any valid disk fid. If no account name is specified, special 


fetch rules apply, as follows. If the file name is specified without a 
trailing period, the file is fetched from :SYS. If a trailing period does 
follow the file name, the file is fetched from the user's current file 
management account. 


source is any valid fid. If this fid ts omitted, the compiler will process 
source text entered from the CR device. 


update is any valid fid. There is no default. 

object is any valid fid. *G file is the default. 

Listout is any valid fid. The LO device is the default. 
optionlist contains rununit specific options, separated by commas. 


Source, update, object, and lListout are also frequently referred to 
respectively as fid1l, fid2, fid3, and fid4, and are collectively referred to 
as the positional fids. 


This invocation performs the following functions for the invoked run unit: 


1. The run unit's designated source DCB is assigned to the source fid if that 
fid is present on the command Line; the flag BSJIT.PRFLAGS.SI is set by 


IBEX. 

2. The run unit's designated update DCB is assigned to the update fid if that 
fid is present on the command Line; the flag BSJIT.PRFLAGS.UI is set by 
IBEX. 
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Unit Invocation Format for Compilers 


3. Similarly, the run unit's designated object and Listout DCBs are assigned 
to the specific object and Listout fids (if present), subject to the 
implications of the preposition preceding these fids, as follows: 


ON causes IBEX to abort the command if either the object or Listout 
file currently exists. 


OVER directs that the object and Listout files are to over-write an 
existing file, if any. Specifically, the MSOPEN options FUN=CREATE, 
EXIST=NEWFILE are added to the assignments. 


INTO directs that if the object or Listout file exists, it is to be 
updated; otherwise, new files are to be created. This corresponds to the 
MSOPEN options FUN=CREATE, EXIST=OLDFILE. 


The flags corresponding to these fields are BSJIT.PRFLAGS.OU and 
BSJIT.PRFLAGS.LS. 
Tad 

These actions occur prior to entry of the invoked run unit. There is more on 
this subject in the CP-6 Programmer Reference Manual on LINK, where the LINK 
options governing DCB associations are described, and itn the CP-6 Monitor 
Services Reference Manual where DCBs and the services connected with them are 
described in detail. 


Consider the example: 
NEWCOMP A,B ON C,LP (SRC.ALPHA),XR) 


Upon entry to NEWCOMP, the following assignments have been merged into 
NEWCOMP's DCBs: 


MSSI = A (disk file); BSJIT.PRFLAGS.SI='1'B. 
MSUI = B (disk file); BSJIT.PRFLAGS.UI='1'B. 
MSOU = C (disk file; BSJIT.PRFLAGS.OU='1'B. 

MS$LO = LP (line printer); BSJIT.PRFLAGS.LS='1'B. 


Note that the invocation, by its use of positional fids, implicitly specified 
the following options: UI, OU, LS. These options need not be specified 
explicitly in the options field of the invocation assuming the the processor 
examines BSJIT.PRFLAGS. Note that the corresponding flags in the BSJIT are 
only modified by the invocation command; there is no Link between the flags 
and any particular DCB name. 
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DCB Usage Conventions 


A processor designed to be invoked by its users via a standard invocation may 
have an interface which allows the user great flexibility in specifying the 
DCBs through which I/0 to the positional fids takes place. If it is not 
desired to provide this flexibility, the processor's programmer may find it 
convenient to require the user to employ the standard DCB default associations 
taken by the LINKer, as described in the LINK section of the CP-6 Programmer 
Reference Manual. 


When a CP-6 processor is LINKed, specific DCBs may be associated with the 
source, update, object, and lListout fields of the Command Processor 
Invocation. To conform to the standard conventions, these DCBs should be: 


e Source DCB = MS$SI 
e Update DCB = M$UI ~ 
e Object DCB = M$OU 
e Listout DCB = M$LO 


The functions associated with these DCBs should also be common: 
MSSI reading of source, base, or command input. 


MSUI reading of update input, to be applied to the base input that ts read 
through M$SI. 


MSOU writing of the generated object unit resulting from the compilation; 
MS$OU should also be used for workspace files, e.g., in APL or BASIC. 


MSLO writing of the generated print file resulting from the compilation. 
Other common DCBs and related functions are: 
MS$SO writing of the merged update and source files to a new file. 


M$DO writing of any error or warning messages; all standard processors witl 
have an M$DO DCB. 


MSME reading and writing of information which is to be dispatched to a 
mode-appropriate device. For instance, EDIT would like its output to appear 
on a terminal if the user is on-line and on the Line printer if the user is in 
batch mode. This behavior is effected by assigning the special name ‘ME' to 
the RES# field of the DCB. 
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Compiler Options Usages and Conventions 


Options are included in compiler-invoking commands to affect the operation of 
the compiler. Presumably, writers of processors which provide options similar 
to those used by the Honeywell supplied compilers will want to use the same 
terms for these options, or at least will want to avoid using these terms in a 
manner inconsistent with their use by the Honeywell supplied compilers, and 
will want to follow similar practices concerning default options. 

Accordingly, Table 14-1 provides definitions of the options considered 
standard for new compilers. Note that in Table 14-1 the prefix N indicates NO 
Ci.e., do not perform the option). The explicit use of the N prefix to an 
option supersedes any implicit assignment of the option. 


Table 14-1. Descriptions of Standard Compiler Options 


Option Description 


BC({ALL|numberL, number] ... }) 


Specifies the sequential number of each procedure in the 
source file to be included as a compile unit. ALL requests 
that all procedures be included. 


CM|INJDMCAPICCoption£, option) ... )] 


Requests that a data map Listing of the compilation object 
unit be written to the device that is associated with the 
position 4 DCB. Defaults, if no contrary action is taken, 
are: the position 4 DCB is M$LO, the associated device is the 
LO device. Options may consist of the following data types: 

AUCTO], BACSED]J, STCATICI], SYCMREFJ. The prefix M requests a 
mini-map that consists of the first Level of a structure only. 


CM|NIJPMCAP) 


Requests that a procedure map indicating the relative 
Locations of external entry points, local subroutines, and 
Labels be written to the device that is associated with the 
position 4 DCB. Defaults, if no contrary action is taken are: 
the position 4 DCB is M$LO, the associated device is the LO 


device. The prefix M requests that the statement locations be 
omitted from the map. 


CM|NISCCHEMA) 


Specifies that debugging schema records are to be written to 
the file that is associated with the position 3 DCB. 
Defaults, if no contrary action is taken, are: the position 3 
DCB is M$OU, the file is that named in the third positional 
fid of the compiler invocation Line. Default file name is *G. 
The prefix M causes schema records to be written only for 
referenced, external, or SYMDEFed items. 
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Table 14-1. Descriptions of Standard Compiler Options (cont.) 


Option Description 


CM|NIXRCEFI 


Requests that a cross-reference Listing of the compiled object 
units be written to the device that is associated with the 
position 4 DCB. Defaults, if no contrary action is taken, 
are: the position 4 DCB is M$L0O, the associated device is the 
LO device. This listing contains a dictionary of symbol 
definitions including all occurrences of all references to the 


definition. The prefix M generates a cross reference for used 
references only. 


CNISYS 


Specifies that, if an INCLUDE statement or directive is 

encountered, the :LIBRARY account is to be searched if the 
file is not found in any of the accounts in the SRCH List. 
SYS is the default. 


Specifies that the symbolic object Listing is to be written to 
the device that is associated with the position 4 DCB. 
Defaults, if no contrary action jis taken, are: the position 4 
DCB is M$LO, the associated device is the LO device. 


Specifies that all source lines are to be written to the 
device that is associated with the position 4 DCB. Defaults, 
if no contrary action is taken, are: the position 4 DCB is 
M$LO, the associated device is the LO device. If LS is not 
specified, only source Lines with errors are Listed. 


Specifies that the update file is to be Listed. Defaults, if 
no contrary action js taken, are: the position 4 DCB is M$LO, 
the associated device ts the LO device. 


Specifies that an object unit is to be generated, and written 
to the file that is associated with the position 3 DCB. 
Defaults, if no contrary action is taken are: the position 3 
DCB is MS$OU, the file is that named in the third positional 
fid in the compiler invocation Line. Default file name is *G. 


Requests that a new source file with updates merged is to be 


written through the M$SO DCB, to the file associated with that 
DCB. 
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Table 14-1. Descriptions of Standard Compiler Options (cont.) 


Option Description 


Specifies that update source code is to be read from the file 
that is associated with the position 2 DCB. Defaults, if no 
contrary action is taken, are: the position 2 DCB is M$UI, 
the file is that named in the second positional fid in the 
compiler invocation line. 


CNIURCEFI 


Requests that a list of unused data references be written to 
the device that is associated with the position 4 DCB. 
Defaults, if no contrary action is taken, are: the position 4 
DCB is M$LO, the associated device is the LO device. 


CNIWACRNJ 


Requests that all warning messages generated by the compiler 
be written through M$DO0. 


SRECH] (list) 


This option augments the specification of the accounts to be 
searched if a language processor encounters an INCLUDE 
statement or other directive which specifies a file only by 
file name. The List is a list of accounts, possibly qualified 
by packset, separated by commas. Each account designation in 
the List must have a Leading period. The accounts are 
searched in the order specified by the List. If the file is 
found in more than one place, the first instance found is the 
one that is included. A maximum of eight accounts may be 
supplied in the List. If the file is not found in any of the 
accounts in the List, the :LIBRARY account and the user's 
running account will then be searched, in that order. Note 


that a search of the :LIBRARY does not take place if the NSYS 
option is specified. 


Specifying positional fids in the invocation of a standard compiler wilt 
implicitly specify certain options, as follows: 


e Specifying the second positional fid (the update fid) constitutes an 
implicit specification of the UI option. 


e Specifying the third positional fid (the object fid) constitutes an 
implicit specification of the OU option. 


e Specifying the fourth positional fid (the listout fid) constitutes an 
implicit specification of the LS option. 


If no option List is specified on the invocation line of a standard compiler, 
the compiler will take, in addition to the implicit options implied by use of 
positional fids, the following standard defaults: 


LS, OU, BCCALL), MSCHEMA, NWARN, SYS 
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If an option List is specified, a standard compiler will supply only three of 
these defaults, as follows: 


e Unless WARN was specified, NWARN will be assumed. 
e Unless NSYS was specified, SYS will be assumed. 
e Unless BC(Llist) was specified, BCCALL) will be assumed. 


Suppose that a compiler called NEWCOMP, conforming to these conventions, is in 
place, and consider the following examples. 


'NEWCOMP 

Sets the options LS, OU, BCCALL), MSCHEMA, SYS, and NWARN (the defaults 
assumed by the compiler). ‘Source will be read through the M$SI DCB, the 
default is the CR device. 

'NEWCOMP A,B ON C,D 


Sets the options UI, OU, LS, BCCALL), MSCHEMA, SYS, and NWARN. Note that OU 
always implies MSCHEMA unless the user specifies otherwise. 


'NEWCOMP A,B ON C,D (NSCHEMA) 
Sets the options UI, BCCALL), SYS, and NWARN. 
'NEWCOMP A,B (LS) 


Sets the options UI, LS, BCCALL), SYS, and NWARN. 


Compiler Error Handling 


Compilers should behave consistently when dealing with errors in the 
specification of options; specifically, the compiler should give an 
appropriate diagnostic and then error the step (issue an MSERR monitor call). 
Errors covered by this general rule include specification of an illegal 
option, repeated options, and inconsistent options. 


If the compiler uses a column-flag method of pointing to errors, ji.e., placing 
a special character beneath the offending statement at the position where the 
error was detected, the following conventions should be observed: 


1. The character used should be a caret or up-arrow '*' (Coctal 136 on the 
ASCII chart). 


2. The offending statement and the flag should both be written through M$DO, 
unless the statement has already been written to the same print 
destination as M$D0. This is to ensure that the error flag is not printed 
out of context. 
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Object Unit Conventions 


The severity level assigned to an object unit by CP-6 compilers should conform 
to the following values (decimal): 


0 no error or warning messages 
4 warning messages issued during compilation 
7 errors were detected which may be sufficient to cause execution failure 


11. fatal error; the object unit contains flaws which will almost certainly 
prevent proper execution 


These values should be stored in the BSOUHEAD.SEVLEV field of the head record 
of the object unit. 


Compiler Output Control Via IBEX 


The CP-6 system uses two IBEX-Level commands to control generation of compiler 
output. These commands are: 


'COMMENT or !DONT COMMENT 

'LIST or !DONT LIST 

These commands cause flags in the JIT to be set or reset (C!DONT case); the 
corresponding flags are BSJIT.PRFLAGS.COMMENT and BSJIT.PRFLAGS.LIST. The 


meaning to compilers should be consistent with the following: 


COMMENT flag = 'O'B; skip all writes through the M$DO DCB. 


‘1'B; perform all writes directed through M$DO DCB. 
LIST flag 


'O'B; skip all M$LO writes 


'1'B; perform all MS$LO writes. 


These flags should be checked for every write through the M$DO and M$LO DCBs, 
since the user may set them at any time. Note that the bits control only the 
specified DCB; the compiler may choose to skip an M$DO write, regardless of 
the COMMENT-bit value, when M$DO and M$LO are both assigned to the same thing 
Cassuming the diagnostic is written through M$LO as well as M$DO). 


The COMMENT and LIST flags are reset by IBEX when a job step terminates; thus 


the DONT-case resetting will only hold through the end of the next 
program/processor invocation. 
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Source Update Services 


The Source Update Package provides input management (XUU) services for 
Language processors which access source input from multiple files. The source 
update services obtain input from: 


e A base source file 
e An update file 
e One or more files referenced by a “read source library file" directive 


Ce.g., the PL-6 ZINCLUDE directive). 


For detailed information on these services, refer to the Monitor Services 
Reference Manual, Library Services section. 
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Section 15 


Interlanguage Calling 


This section discusses the format of calling sequences in the CP-6 system. 

The use of standard calling sequences means that the programs may freely call 
or be called, regardless of the Language in which they are written. Thus 
programs may be created from routines written in COBOL, FORTRAN, PL-6, RPG-II, 
PASCAL, or any other Language with a compiler that uses the standard calling 
sequences. 


In addition to describing calling sequence conventions for user procedures and 
subroutines, this section discusses calls for monitor services and the 
Alternate Shared Library. 


The programmer does not normally need detailed knowledge of the calling 
sequence conventions. However, information in this section is useful in the 
special circumstances listed below: 


e To call the monitor or ASL easily via PL-6 when this capability is not 
provided by run-time support for a language. 


e To write special-purpose subroutines itn machine Language. 
e To call another procedure from machine language. 
e To debug by examining in detail a calling or receiving sequence, a monitor 


call, or an ASL call. 


Thus while the dynamics of a subroutine call might suggest that this 
discussion be presented in the order: calling sequences, receiving sequences, 
return sequence, a different order is chosen to present the most useful 
information first. Topics are presented in the following order: 


Receiving sequences 

Return sequences 

UNWIND Routines 

Automatic Storage Layout 

Calling Sequences for External Routines 

Arguments 

Calls for Monitor and the Alternate Shared Library 
Sample Programs 


The entry and exit routines described in this section are all included in the 
file X6USCSEQU in account :LIBRARY. 


The discussion of calling and receiving sequences refers to the registers 
listed below. For further information on hardware instructions and registers, 
refer to the DPS8& Assembly Instructions (DHO3) manual. 


PRO Pointer Register 0 

PR1 Pointer Register 1 

PR2 Pointer Register 2 (DR2,AR2) 
DR2 Descriptor Register 2 

AR2 Address Register 

X0-X7 Index Registers 0-7 

A Arithmetic Register 

Qa Arithmetic Register 

E Arithmetic Register 


CE62-00 Interlanguage Calling 15-1 


Receiving Sequences 

The receiving sequences for all PL-6 subroutines will be one of the following 
forms depending upon the form of storage used and the type of procedure. 

Note that the receiving sequences documented here are those that will be used 
by PL-6, COBOL, and BMAP programs. Other languages, while using the same 


basic calling sequences, may alter the receiving sequences as required by the 
requirements of the language. 


Table 15-1. Procedure Entry Routines 
Procedure Type Using Auto Using STATIC (NOAUTO) 


MAIN X66_MAUTO X66_MSTATIC 

ASYNC X66_AAUTO X66 _ASTATIC 

Callable Expected X66_ AUTO 0. X66 STATIC_O 
Callable Expected X66_AUTO_1 X66 STATIC 1 
Callable Expected X66 AUTO 2 X66 STATIC 2 
Callable Expected X66_AUTO_ 3 X66 STATIC 3 
Callable Expected X66_AUTO 4 X66 STATIC 4 


Callable Expected X66_AUTO_5 X66 _ STATIC 5 


Callable Expected X66 AUTO_N X66 _STATIC_N 


Each of the procedure entry routines listed in Table 15-1 is entered upon 
procedure activation with the following sequence: 


TSXO X66_ xxx 
ZERO frameinfo, numargs 
where: 
frameinfo defines the procedure activation frame. If the routine is an 


AUTO routine, frameinfo is the required size of the AUTO frame rounded up to 
the nearest even number. If the routine ts a NOAUTO routine, frameinfo is the 
doubleword address in the instruction segment where return address and 
parameters are to be stored. frameinfo must always be an even value. 


numargs is the number of arguments expected by the routine. 


Upon return, the required automatic data is allocated, the argument pointers 
given in this call are moved to the AUTO or NOAUTO frame, and the alternate 
return address jis stored. Note that the value specified for frameinfo must 
include the words required for the. frame header (see below) and the parameter 
pointers. PR2 is updated to locate the new stack frame. 
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Registers Used 


ALL of the routines involving Automatic Data assume that Pointer Register 2 
(DR2, AR2) frames all of the automatic storage and locates the current 
external automatic frame. Thus all programs should Leave PR2 undisturbed. In 
addition, DRO, DR1, X0, X1, X2, X3, X4, A , and @ are used by the receiving 
routines. Alt other registers are not disturbed. 

Note that a subroutine that requires no automatic storage, receives no 
parameters, and calls no other routines need not call any receiving routine. 


It may simply not alter X1 and execute TRA 1,X1 for normal return or TRA 0,X1 
for alternate return. 


Return Sequences 


Table 15-2 defines the exit sequences from various types of procedures: 
Table 15-2. Procedure Return Routines 
Procedure Type Using AUTO Using STATIC (NOAUTO) Registers Used 


MAIN RETURN X66_MARET TRA X66_MSRET 
ASYNC RETURN X66_AARET TRA X66_ASRET 


Callable RETURN X66_ARET LDX1 frame 
TRA 1,X1 


Function RETURN X66 _FARET LDX1 frame 
TRA 1,X1 


MAIN ALTRETURN X66_MAALT TRA X66_MSALT 
ASYNC ALTRETURN X66_AAALT TRA X66_ASALT 


Callable ALTRETURN X66 _AALT LDX1 frame 
TRA 0,X1 


Function ALTRETURN X66_FAALT LDX1 frame 
TRA 0,X1 


In all cases where TRA is recommended to go to a return sequence, TSX2 jis a 
recommended alternative. This can frequently leave useful information for 
debugging. 
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UNWIND Routines 


The following table defines the routine names to be entered for the execution 
of an UNWIND statement for various cases. In all cases A and Q@ are assumed to 
be pre-loaded with an Unwind Variable (A has Auto Pointer for frame to be 
unwound to, @ has EPTR destination). 


Table 15-3. Procedure UNWIND Routines 
Procedure Type Using AUTO Using STATIC (NOAUTO) Registers Used 


MAIN X66 MAUNWIND X66 MSUNWIND 


ASYNC X66_AAUNWIND X66_ASUNWIND 


Callable X66 AUNWIND X66 SUNWIND 


Automatic Storage Layout 


The Layout of automatic storage which is assumed by the calling/receiving 
sequences is as follows: 


1. DR2 frames all of Automatic Storage. 


2. AR2 locates the current external frame which may include several internal 
frames. 


3. The following structures define the required form of each AUTO frame 
header and of the base of AUTO storage. Also shown is a frame for a 
typical PL-6 subroutine with internal procedure. 


DCL 1 AUTO STORAGE FRAME DALIGNED, 
/* 
This structure defines the AUTO frame as used by PL-6. 
The first three words of the frame must also be adhered to 
by all users of AUTOmatic storage. Further storage in the 
frame is managed at the discretion of the Language. 
*/ 
2 RETURN ADDRESS UBIN HALF HALIGNED, 
/* 
This field contains the address of the location after the TSX1 
instruction in a CALL statement, i.e. the location where 
an ALTRET will return. For MAIN and ASYNC procedures 
(no return address), this field contains zero (see loc 
of entry field below). 
* / 
2 NEG PREV_FRAME OFFSET MINUS 1 UBIN HALF HALIGNED, 
/* 
This field contains the complement of the value (offset of 
previous frame + 1). The field is used to set the AUTO pointer 


when returning from a procedure. 
*/ 
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2 FRAME EXTENSION UBIN HALF HALIGNED, 


/* 
This field is used to record the original end of an AUTO frame 
when a frame is extended. 
x / 
2 LANGUAGE FRAME IDENTIFIER UBIN HALF HALIGNED, 
/* 
This field is used to identify the language of the procedure 
to which this frame belongs. 
Valid values and their meanings are as follows: 
-1 PL6 
-2 FORTRAN 
-3 RFU 
“4 RFU 
~16 RFU 
else PL/I(field identifies static father - possibly 0) 
* / 
2 NEXT FRAME OFFSET PLUS 1 UBIN HALF HALIGNED, 
/* 
This field contains the offset to the next frame +1. The +1 
value is stored to avoid overflow when the complement value 
is Loaded from the field. 
x / 
2 LOC_OF_ENTRY_ MAIN OR _ASYNC UBIN HALF HALIGNED, 
/* 
If the return address field contains zero (MAIN or ASYNC) 
then this field will contain the location of the entry 
to the procedure +1. 
*/ 
/* 
The format of the frame through this point is mandatory for 
all frames. The remainder of the frame as described jis for 
PL-6 and BMAP procedures. 
*/ 
2 PARAMS, 
/* 
The following words contain PTR's to the arguments passed 
to this procedure. AS many as required are reserved. 
* / 
3 POINTER1 PTR, 
3 POINTER2 PTR, 
3 POINTERS PTR, 
* / 
2 AUTO VARIABLES AND_TEMP(0:3) BIT(36) 
/* 
The remainder of an AUTO frame is used for storage of AUTO 
variables and temps generated by the compiler. 
*/ 


we 


AUTO_STORAGE_FRAME 


012345678 012345678 012345678 012345678 


ee toon een--- ee ee + DCL 

-0| | | | |1 AUTO STORAGE _FRAME DALIGNED, 
0] uuuuuuuuu |] vuuuuuUUU | | | 2 RETURN_ADDRESS UBIN HALF HA 
.0| | 2 NEG PREV_FRAME OFFSET MINUS 
-0| | | uuuuuuuUU| UUUUUUUUU | UBIN HALF HA 
-1{uuuuuuuuu | uuuuUUUUU | | | 2 FRAME_EXTENSION UBIN HALF HA 
.1{ | | | | 2 LANGUAGE FRAME IDENTIFIER 
-1| | | uuuuuuuUU] UuUuUUUUUUU | UBIN HALF HA 
22 | | | | | 2 NEXT FRAME _OFFSET_PiUS_1 
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.2| wuuuuUUUU | UUUUUUUUU | | | UBIN HALF HA 
.2| | | | 2 LOC_OF_ENTRY_ MAIN _OR_ASYNC 
-2{ | | uuuuuuUUU | UUUUUUUUY | UBIN HALF HA 
3] | | | _ | 2 PARAMS, 
-3| ppppppppp| ppppppppp| ppppppppp| ppppppppp| 3 POINTER1 PTR, 
-4| ppppppppp| ppppppppp| ppppppppp| ppppppppp| 3 POINTER2 PTR, 
-5|ppppppppp| ppppppppp| ppppppppp| ppppppppp| 3 POINTERS PTR, 
.6| | | | 2 AUTO VARIABLES _AND_TEMP(0:3) 
.6|bbbbbbbbb]| bbbbbbbbb| bbbbbbbbb| bbbbbbbbb | B1T(36); 

z z z z z 

to-------- $ee------- $--------- toon e- ee + 


012345678 012345678 012345678 012345678 -12-0-0 total length 


DCL 1 AUTO STORAGE BASE ‘DALIGNED, 


/x 
*/ 
2 
2 
/x 
*x/ 
2 
/* 
*/ 
2 
/* 
x / 
2 
/* 
*/ 
2 
2 


This structure defines the base of the automatic storage segment. 
The items contained are used to control AUTO as a whole, and 


to supply values for initializing each frame. 


INDETERMINATE UBIN HALF HALIGNED, 
NEG CURR FRAME OFFSET MINUS 1 UBIN HALF HALIGNED, 


This field contains the complement of the value(offset of current 
frame +1). This field is used for initializing the ‘previous 


frame' field in the auto frame. It is also used 


to locate the current frame when ASYNC procedures are entered. 


MBZ1 UBIN HALF HALIGNED, 
This field is used to initialize the frame extension field. 


PL6_ FLAG UBIN HALF HALIGNED, 


This field contains the value of the language flag which is proper 


for PL6. 


LIMIT OFFSET UBIN HALF HALIGNED, 


This field contains the value of the last legal offset which 


a frame may reach before further allocation is needed. 


MBZ2 UBIN HALF HALIGNED, 
MBZ3 UBIN; 


AUTO STORAGE BASE 


012345678 012345678 012345678 012345678 
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HAL 
HAL 
HAL 
HAL 
HAL 


$oo------- tenon ----- $onnen---- $oo------- +DCL 
.0| | | | |1 AUTO STORAGE BASE DALIGNED, 
.0| uwuuuuuuuu | uuuuUuUUUU | | | 2 INDETERMINATE UBIN HALF HAL 
-0| | | 2 NEG _CURR_FRAME OFFSET MINUS 1 
-0| | | uuuuuuuUU| UUUUUUUUU| UBIN HALF 
- 1] uuuuuuuuu| uuuuuUUUY| 2 MBZ1 UBIN HALF 
-1| J uuuuuuuuu|uuuUUUUUU| =2 PL6 FLAG UBIN HALF 
.2| uuuuuuuuy | uuuuuuUUU | 2 LIMIT OFFSET UBIN HALF 
-2| JuuuuuuuUU|uUUuUUUUUUU| 2 MBZ2 UBIN HALF 
3] uuuuuuuuU | UuUUUUUUUU| UUUUUUUUU| UUUUUUUUU]) = 2 MBZ3 UBIN; 
$oenen-ee- $oeenn---- ton------- teenen---- + 
012345678 012345678 012345678 012345678 .4-0-0 total length 
Automatic Storage Layout 
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PL6_ FRAME WITH INTERNAL 


012345678 012345678 012345678 012345678 


tenrwererre-n torre wr wm terwrnrre--- teen nmnm----+ DCL 
.0| | | | |1 PL6 FRAME WITH INTERNAL DALIGNE 
-0] uuuuuuuuu |] uuuuUUUUU | | | 2 RETURN ADDRESS UBIN HALF HAL 
-0| | | | 2 NEG _PREV_FRAME OFFSET MINUS 1 
.0| | | wuuuuuUuUU] UuUUUUUUUU | in ™ UBIN HALF HAL 
1] uuuuuuuuu] uuuUUUUUU | | 2 FRAME EXTENSION UBIN HALF HAL 
1 | | | 2 LANGUAGE _FRAME_IDENTIFIER 
o1| | |) wuuuuuuUU| UUUUUUUUU | UBIN HALF HAL 
~2| | | | | 2 NEXT_FRAME OFFSET PLUS 1 
.2| uuuuuuuuu| uuuuUuUUUU| | | ~ . UBIN HALF HAL 
~2| | | 2 LOC_OF_ENTRY_MAIN_OR_ASYNC 
2] | | uuuuuuuUuU] UuUUUUUUUU | ~ UBIN HALF HAL 
-3| | 2 PARAMS, 
-3|ppppppppp| ppppppppp| ppppppppp!| ppppppppp| 3 POINTER1 PTR, 
-4|ppppppppp| ppppppppp! ppppppppp| ppppppppp| 3 POINTER2 PTR, 
-5| ppppppppp| ppppppppp| ppppppppp| ppppppppp| 3 POINTERS PTR, 
-6| | | 2 AUTO VARIABLES _AND_TEMP(0:3) 
-6|bbbbbbbbb| bbbbbbbbb| bbbbbbbbb| bbbbbbbbb | BIT(36), 
z z z z Z 
.12| | | | | 2 INT_FR_A, 
.12| | | | | 3 RETURN ADDRESS 
~12|uuuuuuuuU| uUUUUUUUUU| .. ec ec ecw] eee cece we UBIN HALF, 
13 | 3 PARAMS, 
-13|ppppppppp| ppppppppp!| ppppppppp! ppppppppp| 4 POINTER1 PTR, 
-14| ppppppppp| ppppppppp| ppppppppp| ppppppppp| 4 POINTER2 PTR, 
-15|ppppppppp| ppppppppp| ppppppppp!| ppppppppp| 4 POINTERS PTR, 
: | | | 3 AUTO VARIABLES AND _TEMP(CO: 
.16|bbbbbbbbb| bbbbbbbbb| bbbbbbbbb| bbbbbbbbb | BIT(36), 
z z z z Z 
22] | | | | 2 INT_FR_B, 
~22| | | | | 3 RETURN ADDRESS 
-22|uuuuuuUUU| UUUUUUUUU| 2c ce ee cw ew | wee ccc ee| UBIN HALF, 
~23| | 3 PARAMS, 
-23|ppppppppp| ppppppppp| ppppppppp| ppppppppp| 4 POINTER1 PTR, 
-24|ppppppppp| ppppppppp!| ppppppppp! ppppppppp| 4 POINTER2 PTR, 
-25|ppppppppp| ppppppppp| ppppppppp| ppppppppp| 4 POINTERS PTR, 
; | | 3 AUTO_VARIABLES_AND_TEMP(O: 
.26| bbbbbbbbb| bbbbbbbbb| bbbbbbbbb | bbbbbbbbb| BIT(36); 
z Z z z Z 
$--------- poner ---- $-2n------ $oon------ + 


012345678 012345678 012345678 012345678 -32-0-0 total length 


The basic structure of automatic storage illustrated applies to all users of 
automatic storage. Users may apply more structure to the frame beyond the 
first three words. 


A BMAP subroutine accesses the parameters passed to it by first loading the 
parameter pointers into pointer registers. For example, to load the first 
parameter, an aligned word, into the Q@ register, a routine can use the 
following instructions if an AUTO storage entry routine is used: 


LDP 3,,2 The 3rd word of AUTO is the pointer to the 1st argument 
LDQ 0,,Nn 


or the following instructions if a NOAUTO entry routine is used: 


LDPn STADDR+1 
LDQ 0,,Nn 
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Calling Sequences for External Routines 


ALL calls to external unknown routines must use the following formats. The 
basic form of the call is as follows: 


EPPRO LOC Cpointerlist) Required if arguments present 
EPPR1 LOC (descriptorlist) Required 
TSXI XXX XXX is called routine 
{TRA YYY} Control returned here if XXX 
{TSXn YYY} ALTRETURNS 
{ } 
{NOP } 
‘~ Normal return 
where: 
pointerlist is the List of NSA pointers to actual arguments being passed. 


This List of pointers is made up as necessary depending on the complexity of 
the call. When all arguments being passed are in STATIC or CONSTANT storage, 
the List should be compiled as a block of literals in constant storage. The 
List must be word aligned. 


descriptorlist is described in the following structure: 
DCL 1 ARG DESCRIPTOR _LIST ALIGNED, 
/* 
This structure defines the argument descriptor list which 
must accompany each CALL. This List is located by 
PR1 when the CALL is executed. The List should normally 
be compile time constant and thus should be Located in 
CONSTANT storage. 
*x/ 
2 NUMBER OF ARGS UBIN HALF HALIGNED, 
/* 
This field contains the number of arguments being passed. 
*x/ 
2 V BIT(1), 
/* 
V=0 specifies that the List is a normal argument List 
as specified here. 
V=1 specifies that the list is non-dense with implied ADDRC(NIL) 
for all arguments not passed. This form is not accommodated by the 
setup routines described here. 
x / 
2* BIT(1), 
2 NUM_DESC_ WORDS UBIN(16) UNAL, 
/* 
This field contains the total number of words in the following 
List not including this word. 
«/ 
2 DESC WORDS (O:NUMBER_OF_ARGS~-1) ALIGNED, 
/* 
The following words define each of the arguments being passed. 
*/ 
3 DATA_TYPE UBIN HALF HALIGNED, 
/* 
The data type of the associated argument. See Table 15-4 for 
valid data types. 
x/ 
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/* 


*/ 


/* 


*/ 
/* 


*/ 


/* 


*/ 


/x* 


*/ 


/* 


*/ 


/* 


*/ 
/* 


*/ 


/* 


*/ 


/* 
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3 F BIT(1), 


F=0 specifies that the argument is a data item. 
F=1 specifies that the argument is a subroutine or function 
address. 


3 I BIT(1), 


I=0 specifies that the ARG SIZE field contains the actual size 
of the argument in units appropriate to DATA TYPE. 

See data type list. 

I=1 specifies that the ARG SIZE OFFSET field contains the 

word offset from the beginning of the descriptor extension 
List (DESC EXT). That location contains further information 
about the specification of the actual size. 


3 A BIT(1), 


A=0 specifies that the argument jis being passed as a scalar 
variable. 

A=1 specifies that the argument has an array description 
located by ARG SIZE _OFFSET. 


3 S BIT(1), 


S$=0 specifies that the argument is an elementary data item. 
S=1 specifies that the argument has a structure description 
Located by ARG SIZE OFFSET. 


3 * BIT(1), 
3 ARG SIZE UBIN(13) UNAL, 


If I=A=S=0 and the size of the argument is <2**13 units, then 
this field contains the size of the data item. See data type list. 


3 ARG_SIZE_ OFFSET REDEF ARG SIZE UBIN(13) UNAL, 


If I or A or S$ = 1, then this field contains the offset to 
the descriptor extension word further defining the argument. 
This offset is from the beginning of the descriptor extension 
words. Thus the descriptor extension is located at 
PR1->NUMBER_OF_ARGS+1+ARG SIZE OFFSET. 


DESC _EXT(O:NUM DESC WORDS-NUMBER_OF_ARGS-1) ALIGNED, 


The following words are present only for the exception cases 
specified above. 


3 1 BIT(1), 


I=0 specifies that LARGE SIZE contains the actual size of the 
argument. 

I=1 specifies that the size is Located elsewhere as specified 
below. 


3 A BIT(1), 


A=0 specifies that the actual size is contained in the word 
located by STATIC LOC OF SIZE. 

A=1 specifies that the actual size is contained in the word 
in the caller's AUTO frame located by AUTO OFFSET OF SIZE. 
Note that A is ignored if I=0. 


3 * BIT(7), 
3 LARGE SIZE UBIN(27) UNAL, 


Actual size of the argument. 
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3 STATIC_LOC_OF SIZE REDEF LARGE SIZE UBIN(27) UNAL, 


The location within the Instruction Segment which contains 


the actual size. 


3 AUTO_OFFSET OF SIZE REDEF LARGE SIZE UBIN(27) UNAL 


The offset within the caller's automatic frame which contains 


the actual size. 


*/ 


Ne 


ARG DESCRIPTOR LIST 


012345678 012345678 012345678 012345678 


$e enew ewe few wm wens 


uuuuUuUuUU 


Po 


2 
1421421 


iJ e ty ty s e e . e e e e e e e e s s e e s s 8 e e 
NNUNNNVNNNNNH ABABA w owe owo3=2GDOO00 


$--------- toeno- =e tonne --- tere------ + 
012345678 012345678 012345678 012345678 
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| uuuuuuuUU| UuUUUUUUUU] UUUUUUUUU 


uuuUuUUUUU | UuUuUUUUUUU 


uuuuUuUuUUU 


ee cee ee eee cee eS SS a eS LE Se A ED a ef 


1421421|1421421421 


14211421421421 
| 


1421|421421421 
| 


ihetetatatatated +DCL 


}1 ARG DESCRIPTOR LIST ALIGNED, 


| wwuuuuUUU] UUUUUUUUU | UUUUUUUUU | 


| wuuuuuuuU] UUuUUUUUU] UUUUUUUUU | 
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2 NUMBER_OF_ARGS 
2 Vv 


UBIN HALF HAL 
BIT(1), 
2k BIT(1), 
2 NUM DESC WORDS UBIN(16) UNAL 
2 DESC WORDS (O:NUMBER_OF ARGS-1 


3 DATA TYPE UBIN HALF HAL 
3F 7 BIT(1), 
3 1 BIT(1), 
3 A BIT(1), 
38 BIT(1), 
3 BIT(1), 
3 ARG SIZE UBIN(13) UNAL 
3 ARG _SIZE_OFFSET REDEF ARG S 


UBIN(13) UNAL 
2 DESC_EXT(O:NUM_DESC_WORDS-NUM 


ALIGNED, 
31 BIT(1), 
3A BIT(1), 
3 BIT(7), 
3 LARGE SIZE UBIN(27) UNAL 
3 STATIC LOC OF SIZE REDEF LA 


“UBINC27) UNAL 
AUTO OFFSET OF SIZE REDEF L 
UBIN(27) UNAL 


W 


-3-0-0 total Length (variable) 
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Table 15-4. Data Types for Arguments 


Data Type Bits/Unit Description _ 


Type not specified 

Binary fixed point single (SBIN, INTEGER, COMP-6) 
Binary fixed point double precision 

Binary(Hex exp) float single CREAL) 

Binary(Hex exp) float double (DOUBLE PRECISION) 
Complex binary fixed point single 

Complex binary fixed point double 

Complex binaryChex exp) float single(COMPLEX) 
Complex binaryChex exp) float double(DOUBLE COMPLEX) 
Packed decimal fixed, lead ASCII sign (COMP~-4) 
Packed decimal float 

Complex packed decimal fixed,lead ASCII sign 
Complex packed decimal float 

Pointer (18 word, 2 byte, 4 bit, 12 segid) 
Offset 

Label 

Entry 

Structure Caggregate) 

Area 

Bit string 

Varying bit string 

Character string 

Varying character string 

File 

Unsigned binary fixed point single (UBIN) 
Packed decimal fixed, trail ASCII sign (COMP,COMP-4) 
Adjustable character string 

Adjustable bit string 

Entry pointer (CEPTR) 

16 bit signed integer (2 bytes) (COMP-1) 

32 bit signed integer (4 bytes) (COMP~2) 

Packed decimal fixed, trail EBCDIC sign (COMP-3) 
INDEX~1 

INDEX-2 

Fortran EVERY 

Fortran LOGICAL 

Fortran ANY (never passed) 

Fortran LABEL 

Fortran UCB 

Intrinsic constant 

Packed decimal fixed, no sign (COMP,COMP-3,COMP-4) 
Unpacked decimal fixed, no sign 

Unpacked decimal fixed, lead sign 

Unpacked decimal fixed, trail sign 

Unpacked decimal fixed, lead overpunched sign 
Unpacked decimal fixed, trail overpunched sign 
Adjustable structure 

Vector 

Remember 

Descriptor 

Reserved 

Used in debug schema of object unit 


WAONAUFWAN 3 © 
— tro oe = 
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DELTA Interaction with Shared Libraries 


When DELTA is tracing the flow of execution which includes calls to shared 
Libraries, the following assumptions are made about TSX instructions which 
reference the shared Library: 


e TSXO is always followed by a non-executable word of information. 


e TSX1 is always followed by a instruction to be executed when an alternate 
return is taken (generally a NOP, TRA, or TSXn). 


e TSX2 will not return and is functionally identical to TRA. 


Calls to the Monitor and Alternate Shared Library 


Transfer of control from one domain to another via the CLIMB instruction. The 
user may call on the monitor by using the PMME form of the CLIMB. He may 
CLIMB to the Alternate Shared Library directly. This subsection describes the 
standard calling sequence to be used to enter another domain. 


Monitor-User Interface 


A monitor service is invoked by the PMME form of the CLIMB instruction. 
Associated with each montior service is a unique Function Parameter Table 
CFPT) that supplies the monitor with user-specific information to be used in 
processing the service request. 


The format of this machine instruction is as follows: 


° 18 28 29 30 35 
ee a ee eee ey 
| ADDRESS [OP CODE|I [ARI TAG| 
J ALT PMMECODE | (CLIMB) 
0 1 7 18 
? 1 18 19 20 24 26 35 
| ee ie ae ee 
| P Ix Im ic | s [oo | 
| ; {| {| [| Jf | 
ADDRESS Identifies the unique service request and an optional error return: 


Bit O When set indicates that the instruction following the CLIMB is the 
alternate return. It is to be executed if the monitor cannot successfully 
complete the service request. If successfully completed, control jis 
returned skipping this instruction. 


When Bit 0 is reset, there is no alternate return address. In this case the 
monitor aborts the user if the service cannot be completed successfully. 


Bit 1-17 Uniquely identify the type of service request. The code defining 
each monitor service (FCG and PMME code) as well as the structure of each 
FPT is defined in the INCLUDE file CP_6. 


S$, D = 1760 Indicates that this instruction is a PMME. 
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C = 00 Indicates an Inward CLIMB (CALL). Allows for descriptors to be 
prepared and placed on the Argument Stack. A new Parameter and Argument 
Segment are framed, and the processor state is saved. Other values of C 
indicate other types of CLIMB which are not relevant to the present 
discussion. 


Xx = 1 Specifies loading of the effective address of the instruction into 
Index Register 0 after the context is pushed into the Safe Store STack. 


E- —€ = 0 Indicates that the service call does not require any parameters. 
E=1 if parameters are to be passed to the monitor on the Parameter Stack. If 
E=1, DRO must contain a descriptor framing the parameters to be passed. 

P Specifies the number of parameters minus 1. P is ignored if E=0. 


Details concerning the parameters that must be specified are described in the 
CP-6 Monitor Services Reference manual. The FPT contains all information 
required for building the monitor's Parameter Stack and for performing the 
service for the user. 
There are two possible sections to an FPT: 
1. Vectors framing arguments, expressed as addresses in the user's area. 
This section of the FPT defines the monitor's Parameter Stack. If the FPT 
contains value parameters, the first of these vectors frames the data 
block that contains these values. 
2. A data block containing the value parameters. 


Each vector in the FPT is of the following format: 


20 29 31 35 


; 

| BOUND FLAGS v |/s| 
| pp | 
| BASE ADDRESS l////|s | 

0 


| 
20. 24 26 35 


01 Indicates a request for a normal shrink of the descriptor defined by 


S, D Identifies the descriptor to be shrunk. 


FLAGS Should all be set. The shrunken descriptor will have the same 
permissions as the descriptor in the Linkage Segment. 


BOUND Specifies the byte size minus 1 of the area being passed as a 
parameter. 


BASE ADDRESS Specifies the byte offset into the segment defined by the 
descriptor that is specified by S,D. 


If the hardware is to prepare the monitor's Parameter Stack, PRO must be 
loaded with a descriptor prior to executing the PMME CLIMB instruction. PRO 
locates a vector List which is used to shrink descriptors to be placed on the 
stack. 


A typical monitor service calling sequence is then: 

1. Generate the value parameters as required by the service call. 

2. Generate vectors framing areas of memory to build descriptors that the 
monitor expects to find on the Parameter Stack. 


NOTE: Steps 1 and 2 are frequently accomplished by compiling the correct 
values. 
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3. Load DRO with the descriptor that the hardware may use to build the 
Parameter Stack. 


4. Execute the PMME form of the CLIMB instruction. Follow with an 


instruction to transfer control to an error routine if the CLIMB had the 
ALTRET bit set in the address field. 


ASL-User Interface 


The form for calls to the Alternate Shared Library is identical to that for 
calling the monitor with two exceptions: 


1. There is no provision for alternate return. 


2. The S,D field of the CLIMB should contain the value of ASLENTSID. This 
value will be supplied by the Linker if a program contains a SEGREF 
ASLENTSID. 


Sample Programs 


Two sample programs are shown in Figures 15-1 and 15-2 which display code 
typically generated for standard calling and receiving sequences. 
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1.000 

1.100 

2.000 

3.000 

3.100 

3.200 

3.300 

4.000 

4.100 

5.000 

6.000 

6.100 

7.000 

7.100 

8.000 

8.100 

9.000 

10.000 

000000000003 11.000 
000000000004 12.000 
000000000005 13.000 

14.000 

15.000 

0 000000 x 000000 7000 00 16.000 
16.100 

000001 000006 000003 17.000 
17.100 

17.200 

17.300 

000002 2 00004 4705 00 19.000 
000003 2 00005 4715 00 20.000 
000004 2 00003 4735 00 21.000 
000005 000001 6140 04 22.000 
000006 000001 6150 04 23.000 
000007 0 00000 4311 00 24.000 
000010 1 00000 4751 00 25.000 
000011 3 00000 4551 00 26.000 
000012 x 000000 6140 00 27.000 
27.100 

000013 x 000000 6150 00 28.000 
28.100 

000014 x 000000 7100 00 29.000 
30.000 

31.000 

32.000 

(0)000000000015 33.000 

33.100 

34.000 

34.100 

000015 000000 6170 11 35.000 
000016 000001 7100 11 36.000 
37.000 


CONTROL SECTION TABLE 


O CODE EVEN 000017 
1 RODATA EVEN 000000 LITERALS 


8 SYMBOLS 


0 MACROS 


*M* Sample BMAP subroutines showing 


* use of standard receiving sequences 
ENTOEF TOV 
ENTDEF FAD 
* Add two floating point 
* numbers, giving a third 
* 
* First argument is SUM, 2nd 
* and 3rd are addends 
* 
ENTREF X66 AUTO 3 
* Set up args and allocate AUTO 
ENTREF X66 _ARET 
* Take normal return, free AUTO 
ENTREF X66 _AALT 
* Take altret, free AUTO 
* 
* Define Locations in AUTO frame 
SUM EQU 3 
ADDEND1 EQU 4 
ADDEND2 EQU 5 
* 
* 
FAD TSXO X66 AUTO 3 
* Allocate AUTO, set up args 
ZERO 6,3 
* Allocate 6 words, set up 3 
* args. 6 words are for 
* 3 header, 3 args, O local 
LDPO ADDEND1,,2 
LoOP1 ADDEND2,,2 
LDP3 SUM, ,2 
TEO 1,1€ reset overflow 
TEU 1 eee 6 and underflow 
FLD 0,,0 
FAD 0,,1 
FST 0,,3 
TEO X66_AALT 
* Altret if overflow 
TEU X66 AALT 
* -.-or underflow 
TRA X66_ARET 
* 
* 
* 
TOV EQU * 
* This routine requires no auto, 
* and has no arguments, so it is 
* simply: 
TOV 0,1 ALTRETURN 
TRA 1,1 RETURN 
END 


Figure 15-1. BMAP Program - Standard Receiving Sequences (cont. next page) 
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SYMBOL SPACE USED 61 WORDS 
MACRO SPACE USED 
INPUT RECORDS READ 
STATEMENTS PROCESSED 


ELAPSED TIME 
CPU TIME 
ASSEMBLY RATE 2169 STATEMENTS/CPU MIN. 


NO ERRORS 


Figure 15-1. BMAP Program - Standard Receiving Sequences 
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'PL6 PL6 EG (LO) 
PL6 BO2 here at 09:52 SEP 27 '83 


Include file information -- 
CP_6.:LIBRARY 
BSJIT_C.:B030U 
CP_6 C.:BO3TOU 


cannot be made into 


No diagnostics issued 
Procedure SAMPLE requires 48 words 
Procedure SAMPLE requires 14 words 


Object Unit name= SAMPLE 
UTS= SEP 27 '83 09:52:46.89 TUE 
SharedLib= :SHARED SYSTEM 


a system file and is referenced. 


was found in the system file and is never referenced. 
was found in the system file and is referenced. 


in procedure SAMPLE 


for executable code. 
of lLocalCAUTO) storage. 


File name= *G. 
Compiler= PL-6/B02 Severity=00 
Alt SharedLib= 


keke Control sections «xxx 
Sect Type Bound Init Size OctSiz Section name(segment info) 
0 DCB even UTS 0 O m$UC 
1 Data even UTS 30 36 SAMPLE 
2 Proc even none 48 60 SAMPLE 
3 RoData even’ none 6 6 SAMPLE 
week Entry defs «xxx 
Check Calling 
calling sequence 
Sect OctLoc Primary Altret sequence type Parms Name 
2 0 yes yes yes Std 2 SAMPLE 
keke Entry refs kk 
Check Calling 
calling sequence 
Altret sequence SRef type Args Name 
yes yes Std 3 SUBR 
yes Std 3. SUBR1 
nstd 0 X66_AUTO 2 
nstd O X66 _AALT 
nstd O X66 _ARET 
kkk Data refs keke 
Flags: r = read only, s = secondary 
Flas Name Flgs Name Flos Name 
MSUC 
keke «Segment refs «xx 
Flags: r = read only, s = secondary 
Figs Name Flos Name Flas Name 
ISSID NULLSID 
1.000 1 /*Mx* Sample to show calling sequence features*/ 
2.000 2 SAMPLE: PROC (PAR1,PAR2) ALTRET; 
2 2 000000 000000 700200 xent SAMPLE TSXO ! X66 AUTO 2 
2 2 000001 000016 000002 ZERO 14,2 


Figure 15-2. 
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Programs 
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3.000 
4.000 
5.000 
6.000 
7.000 
8.000 
9.000 

10.000 


3 /*Procedure accepts 2 parameters & may altret*/ 

4 1 DCL PAR1 UBIN; 

5 1 DCL PAR2 CHAR(8); 

6 /xParameters: all references are through 

7 PTRs prepared by setup routines.*/ 

8 1 DCL LCL1 UBIN; 

9 1 DCL LCL2 CHAR(12); 

10 1 DCL LCL3 UBIN; 

11.000 11 /xLocal variables referenced directly in 

12.000 12 Instruction Segment or through PR2 

13.000 13 depending on whether procedure is 
14 
15 
16 
17 
18 
19 
20 


14.000 compiled NOAUTO or not*/ 
15.000 1 DCL SUBR ENTRY(C3) CONVC(O) ALTRET; 
16.000 1 DCL SUBR1 ENTRY(3); 


17.000 /*xTwo subroutines may be called, the 
18.000 first allowing ALTRETURN and 

19.000 requiring all sizes to be specified 
20.000 


and the second not permitting 


21.000 21 ALTRETURN and not requiring sizes.*/ 
22.000 22 ZINCLUDE CP_6; 

23.000 99 ZFPT_CLOSE; /*Declare FPT for monitor call*/ 
24.000 127 

25.000 128 

26.000 129 1 LCL1 = PAR1; 


129 2 000002 200003 470500 LOPO #PAR1,,AUTO 
129 2 000003 000000 235100 LDA 0,,PRO 
129 2 000004 200005 755100 STA LCL1,,AUTO 


27.000 130 1 LCL2 


130 2 000005 200004 471500 LDP1 HPAR2,,AUTO 

130 2 000006 040100 100500 MLR fill="040'O 

130 2 000007 100000 000010 ADSCI 0,,PR1 cn=0,n=8 

130 2 000010 200006 000014 ADSC9 LCL2,,AUTO cn=0,n=12 


28.000 131 1 LCL3 


131 2 000011 000000 235100 LDA 0,,PRO 
131 2 000012 200011 755100 STA LCL3,,AUTO 


29.000 132 /xnote re-use of same PTR*/ 
30.000 133 1 CALL SUBR (LCL1,PAR2,SUBSTR(LCL2,0,LCL1)) ALTRET 
133 (LBL); 


133 2 000013 200005 236100 LDa LCL1,,AUTO 
133) 2 000014 200015 756100 STQ LCL3+4,,AUTO 
133) 2 000015 200006 633500 EPPR3 LCL2,,AUTO 
133 2 000016 200014 453500 STP3 LCL3+3,,AUTO 
133 2 000017 200004 236100 Loa #PAR2,,AUTO 
133) 2 000020 200013 756100 STQ LCL3+2,,AUTO 
133 2 000021 200005 634500 EPPR4 LCL1,,AUTO 
133 2 000022 200012 454500 STP4 LCL3+1,,AUTO 
133 2 000023 200012 630500 EPPRO LCL3+1,,AUTO 
133 2 000024 000000 631400 3 EPPR1 0 

133. 2 000025 000000 701000 xent TSX1 SUBR 

133 2 000026 000045 702000 2 TSX2 LBL 


31.000 134 /xSubroutine called, Altreturn accepted 

32.000 135 Argument List includes: 

33.000 136 argument passed in, size implied by 
33.100 137 data type 

34.000 138 argument is Local variable, size is 
35.000 139 constant(12) 

36.000 140 argument jis local, size computed at 
36.100 141 exeuction*/ 

37.000 142 1 LCL1 = PAR1; 


Figure 15-2. PL-6 Program - Receiving/Calling Sequences (cont. next page) 
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142 
142 
142 


38.000 
38.100 


144 
144 
144 
144 


38.200 
38.300 


146 
146 
146 


39.000 


147 
147 
147 


LDPO 
LDA 
STA 


#PAR1,,AUTO 
0,,PRO 
LCL1,,AUTO 


/*xNote PTR requires reloading after CALL*/ 


2 000027 200003 470500 
2 000030 000000 235100 
2 000031 200005 755100 
143 
144 1 


NM NN PO 


000035 


145 


146 


000045 


1 


702000 2 


000032 000000 630400 1 
000033 450001 713400 
000034 406000 401760 


EPPRO 
CLIMB 


pmme 
TSX2 


CALL MSCLOSE (CFPT_CLOSE) ALTRET (LBL); 


FPT_ CLOSE 
alt,close 
nvectors=13 
LBL 


/*Monitor call with altreturn specified*/ 


2 000036 200003 470500 
2 000037 000000 235100 
2 000040 200005 755100 


147 


1 


2 000041 000000 630400 1 
2 000042 050001 713400 
2 000043 406000 401760 


40.000 
41.000 


149 


42.000 
43.000 


151 
151 
151 
151 
151 
151 
151 
151 
151 
151 


44.000 
45.000 
46.000 


FPT_CLOSE 


1 000000 
000004 
000010 
000014 
000020 
000024 
000030 
000034 


—_ af — -3 —3 «2 = 


Figure 15-2. 
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2 


NNNNNN NNN PY 


154 2 


14 
14 


000044 


15 
15 


000045 
000046 
000047 
000050 
000051 
000052 
000053 
000054 
000055 
000056 


15 
15 
15 


000057 


Sect OctLoc 


000003 
000000 
000000 
000000 
000000 
000000 
000000 
000220 


8 
9 1 


000000 


0 
1 1 


200006 
200014 
200004 
200013 
200005 
200012 
200012 
000005 
000000 
000000 


2 
3 
4 1 


000000 


777640 
177640 
177640 
177640 
177640 
177640 
177640 
000000 


LBL: 


000032 
000000 
000000 
000000 
000000 
000000 
000000 
000000 


PL-6 Program - 


LCL1 = PAR1; 


LDPO 
LDA 
STA 


CALL MSCLOSE (CFPT_CLOSE); 


EPPRO 
CLIMB 


pmme 


HPAR1,,AUTO 
LCL1,,AUTO 


FPT_CLOSE 
close 
nvectors=13 


/*Monitor call with no altret specified*/ 


702200 xent 


ALTRETURN; 


TSX2 


! X66 AALT 


/*xTake alternate return from SAMPLE*/ 


CALL SUBR1 (LCL1,PAR2,SUBSTR(LCL2,0,LCL1)); 


630500 
450500 
236100 
756100 
631500 
451500 
630500 
631400 3 
701000 xent 
011000 


LBL 


EPPRO 
STPO 
LDQ 
STQ 
EPPR1 
STP1 
EPPRO 
EPPR1 
TSX1 
NOP 


LCL2,,AUTO 
LCL3+3,,AUTO 
HPAR2,,AUTO 
LCL3+2,,AUTO 
LCL1,,AUTO 
LCL3+1,,AUTO 
LCL3+1,,AUTO 
5 

SUBR1 

0 


/*Same as call to SUBR above except no altret 
and no size information required*/ 


RETURN; 


702200 xent 


000000 
000000 
000000 
000000 
000000 
000000 
000000 
000000 


000000 
000000 
000000 
000000 
000000 
000000 
000000 


177640 
177640 
177640 
177640 
177640 
177640 
000000 


Sample Programs 


TSX2 


000000 
000000 
000000 
000000 
000000 
000000 
000000 


Receiving/Calling Sequences (cont. 


! X66 _ARET 


000000 ........ 
000000 ....... ° 
000000 ........ 
OOOO00DO ....wceeeee 
ooooo00 ...... ee 
OO0000 .......-. 
000040 .......- 


next page) 
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Cunnamed) 

Sect OctLoc 

3 000000 000003 000004 000030 000044 000025 000010 000032 200000 

3 000004 600000 000015 000003 O00000 ........ 
47.000 155 /*Take normal return from SAMPLE*/ 
48.000 156 1 END; 
49.000 157 %EOD; 


Include file information -- 
CP_6.:LIBRARY cannot be made into a system file and is referenced. 
BSJIT_C.:B030U was found in the system file and is never referenced. 
CP_6 C.:BO3TOU was found in the system file and is referenced. 


No diagnostics issued in procedure SAMPLE 


Procedure SAMPLE requires 48 words for executable code. 
Procedure SAMPLE requires 14 words of Local(CAUTO) storage. 


Include file information -- 


CP_6.:LIBRARY cannot be made into a system file and is referenced. 
BSJIT_C.:B030U was found in the system file and is never referenced. 
CP_6_C.:BO3TOU was found in the system file and is referenced. 


No diagnostics issued in procedure SAMPLE 


Procedure SAMPLE requires 48 words for executable code. 
Procedure SAMPLE is declared NOAUTO and requires 42 words of local 
(STATIC) storage. 


No errors detected in file PL6 EG.DHEXMPL 


Object Unit name= SAMPLE File name= *G, 
UTS= SEP 27 '83 09:53:26.18 TUE Compiler= PL-6/B02 Severity=00 
SharedLib= >SHARED SYSTEM Alt SharedLib= 


keke = €6Control sections x*xx* 


Type Bound Init Size OctSiz Section name(segment info) 
Data even UTS 42 52 SAMPLE 

DCB even UTS 0 QO MS$UC 

Proc even none 48 60 SAMPLE 
RoData even none 8 10 SAMPLE 


week Entry defs xxx 


Check Calling 
calling sequence 
OctLoc Primary Altret sequence type Parms Name 
0 yes yes yes Std 2 SAMPLE 


Entry refs «kx 


Check Calling 
calling sequence 
Altret sequence SRef type Args Name 
yes yes Std 3. SUBR 
yes Std 3 SUBR1 
nstd 0 X66_STATIC 2 


Data refs tk 


Figure 15-2. PL-6 Program - Receiving/Calling Sequences (cont. next page) 
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Flags: r= read only, s = secondary 


Flags Name Flgs Name Flgs Name 
MSUC 
keke Segment refs «xx 
Flags: r= read only, s = secondary 
Flos Name .Flas Name Flgs Name 
ISSID NULLSID 
50.000 1 SAMPLE: PROC (CPAR1,PAR2) ALTRET NOAUTO; 
1 2 000000 000000 700200 xent SAMPLE TSXO ! X66 STATIC 2 
1 2 000001 000000 Q00002 O ZERO 0,2 
51.000 2 /*xProcedure accepts 2 parameters & may altret*/ 
52.000 3 1 DCL PAR1 UBIN; 
53.000 4 1 DCL PAR2 CHAR(8); 
54.000 5 /*Parameters: all references are through 
55.000 6 PTRs prepared by setup routines.*/ 
56.000 7 1 DCL LCL1 UBIN; 
57.000 8 1 DCL LCL2 CHAR(12); 
58.000 9 1 DCL LCL3 UBIN; 
59.000 10 /xLocal variables referenced directly in 
60.000 11 Instruction Segment or through PR2 
61.000 12 depending on whether procedure is 
62.000 13 compiled NOAUTO or not*/ 
63.000 14 1 DCL SUBR ENTRYC3) CONVCO) ALTRET; 
64.000 15 1 DCL SUBR1 ENTRY(3); 
65.000 16 /xTwo subroutines may be called, the 
66.000 17 first allowing ALTRETURN and 
67.000 18 requiring all sizes to be specified 
68.000 19 and the second not permitting 
69.000 20 ALTRETURN and not requiring sizes.*/ 
70.000 21 ZINCLUDE CP_6; 
71.000 98 ZFPT_ CLOSE; /*Declare FPT for monitor call*/ 
72.000 126 
73.000 127 
74.000 128 1 LCL1 = PARI; 
128 2 000002 000001 470400 O LDPO #PAR1 
128 2 000003 000000 235100 LDA 0,,PRO 
128 2 000004 000003 755000 O STA LCL1 
75.000 129 1 LCL2 = PAR2; 
129 2 000005 000002 471400 O LDP1 HPAR2 
129 2 000006 040000 100500 MLR fill='040'0O 
129 2 000007 100000 000010 ADSCc9 0,,PR1 cn=0,n=8 
129 2 000010 000004 000014 0 ADSC9 LCL2 cn=0,n=12 
76.000 130 1 LCL3 = PARI; 
130 2 000011 000000 235100 LDA 0,,PRO 
130 2 000012 000007 755000 O STA LCL3 
77.000 131 /*xnote re-use of same PTR*/ 
78.000 132 1 CALL SUBR (LCL1,PAR2,SUBSTR(LCL2,0,LCL1)) ALTRET 
132 (LBL); 


posses sranssreeeenssanassersanenensieanpentnancpeinad 


Figure 15-2. PL-6 Program - Receiving/Calling Sequences (cont. next page) 
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132 
132 
132 
132 
132 
132 
132 
132 
132 
132 
132 


79.000 
80.000 
81.000 
82.000 
83.000 
84.000 
84.100 
84.200 
85.000 


141 
141 
141 


86.000 
87.000 


143 
143 
143 
143 


88.000 
88.100 


145 
145 
145 


88.200 


146 
146 
146 


88.300 
89.000 


148 
148 


90.000 
91.000 


150 
150 
150 
150 
150 
150 
150 
150 
150 


Figure 15-2. 
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NUNNNNNN NM NH PP 


2 
2 
2 


2 
2 


2 
2 
2 


2 
2 


MN NM MN MPP PP 


000013 
000014 
000015 
000016 
000017 
000020 
000021 
000022 
000023 
000024 
000025 


133 
134 
135 
136 
137 
138 
139 
140 
141 


000026 
000027 
000030 


142 
143 


000031 
000032 
000033 
000034 


144 
145 


000035 
000036 
000037 


146 


000040 
000041 
000042 


147 
148 


000043 
000044 


149 
150 


000045 
000046 
000047 
000050 
000051 
000052 
000053 
000054 
000055 


000003 
000051 
000005 
000050 
000002 
000006 
000046 
000046 
000000 
000000 
000045 


1 


000001 
000000 
000003 


1 


000010 
450001 
406000 
000045 


1 


000001 
000000 
000003 


1 


000010 
050001 
406000 


1 


000000 
000000 


1 


000005 
000050 
000002 
000006 
000046 
000046 
000007 
000000 
000000 


LBL: 


LDQ LCL 

STQ FPT_ CLOSE+33 
LDQ 5 

STQ FPT_CLOSE+32 
LDQ HPAR2 

LDA 6 

STAQ FPT CLOSE+30 
EPPRO FPT_CLOSE+30 
EPPR1 0 

TSx1 SUBR 

TSX2 LBL 


236000 
756000 
236000 
756000 
236000 
235000 
757000 
630400 
631400 
701000 
702000 


NX WOOWOOWOO 
oO 
3 
et 


/*Subroutine called, Altreturn accepted 

Argument List includes: 

argument passed in, 

data type 

argument is tocal variable, size is 
constant(12) 

argument is Local, size computed at 
exeuction*/ 


size implied by 


LCL1 = PAR1; 
470400 0 

235100 

755000 0 


HPAR1 
0,,PRO 
LCL1 


LDPO 
LDA 
STA 


/*Note PTR requires reloading after CALL*/ 
CALL MSCLOSE CFPT_CLOSE) ALTRETCLBL); 


630400 0 
713400 
401760 
702000 2 


EPPRO 
CLIMB 
pmme 
TSX2 


FPT CLOSE 
alt,close 
nvectors=13 
LBL 


/*Monitor call with altreturn specifiedx/ 
LCL1 = PARI; 


470400 0 
235100 
755000 O 


HPAR1 
0,,PRO 
LCL1 


LDPO 
LDA 
STA 


CALL MSCLOSE CFPT_CLOSE); 


630400 0 
713400 
401760 


EPPRO 
CLIMB 
pmme 


FPT_CLOSE 
close 
nvectors=13 


/*xMonitor call with no altret specified*/ 
ALTRETURN; 


221200 0 
702211 


Lox1 ! 0 
TSX2 ! O,X1 


/xTake alternate return from SAMPLEx/ 
CALL SUBR1 (LCL1,PAR2,SUBSTR(LCL2,0,LCL1)); 


236000 
756000 
236000 
235000 
757000 
630400 
631400 
701000 
011000 


LBL Lda 5 

STa@ FPT CLOSE+32 
LDQ HPAR2 

LDA 6 

STAQ FPT_CLOSE+30 
EPPRO FPT_CLOSE+30 
EPPR1 7? 

TSX1 SUBR1 

NOP 0 
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92.000 151 /*Same as call to SUBR above except no altret 
93.000 152 and no size information required*/ 
94.000 153 1 RETURN; 


153. 2 000056 000000 221200 0 | LDX1 ! 
153 2 000057 000001 702211 TSX2 ! 1,X1 


FPT CLOSE 

Sect OctLoc 
000010 000003 777640 000042 000000 000000 177640 000000 000000 
000014 000000 177640 000000 000000 000000 177640 000000 
000020 000000 177640 000000 000000 000000 177640 000000 
000024 000000 177640 000000 000000 000000 177640 000000 OO0000 ........... 
000030 000000 177640 000000 000000 000000 177640 000000 OO0000 ........... 
000034 000000 177640 000000 000000 000000 177640 000000 OO0000 ........... 
000040 000000 177640 000000 000000 000000 000000 000000 O00040 ........... 
000044 000220 000000 000000 OO00000 ........ 


Cunnamed) 

Sect OctLoc 

3 000000 000003 000004 000030 000044 000025 000010 000032 200000 .......$ 

3 000004 400000 000051 000004 000000 000003 000000 000003 OO00000 ...») 
95.000 154 /*Take normal return from SAMPLE*/ 
96.000 155 1 END; 


-- Include file information -- 
CP_6.:LIBRARY cannot be made into a system file and is referenced. 
BSJIT_C.:BO030U was found in the system file and is never referenced. 
CP_6 C.:BO3TOU was found in the system file and is referenced. 
No diagnostics issued in procedure SAMPLE 
Procedure SAMPLE requires 48 words for executable code. 


Procedure SAMPLE is declared NOAUTO and requires 42 words of local 
(STATIC) storage. 


No errors detected in file PL6_EG.DHEXMPL 


Figure 15-2. PL-6 Program - Receiving/Calling Sequences 
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Appendix A 


Job Information Table 


A discussion of accessing the Job Information Table (JIT) is included in 
Section 8 of this manual. This appendix includes descriptions of JIT fields 
and a depiction of the JIT structure. 


JIT Fields 


The following fields are contained in the JIT: 


ACCESS. 

ACCESS. The ACCESS field contains counts of various kinds of physical 
accesses to devices. 

ACCESS.FORMS 

ACCESS.FORMS - SBIN. The FORMS field counts the number of physical accesses 
to resource devices other than disk or tape (e.g. resource Line Printer). 
ACCESS.PACKS 

ACCESS.PACKS - SBIN. The PACKS field counts the number of physical accesses 
to files during this job or session. Also included are requested physical 
accesses which were satisfied by the I/0 cache. 

ACCESS.TAPES 

ACCESS.TAPES - SBIN. The TAPES field counts the number of physical accesses 
to tapes during this job or session. 

ACCN 


ACCN - CHAR(8). The ACCouNt field contains the user's log on account. 


ARECX 
ARECX - UBIN(16). The Accounting RECord index field contains the key to be 


used in the next resource accounting record to be written to *S. This field is 
incremented each time a resource accounting record is written. 


BILL 


BILL - CHAR(6). The BILL field is used to locate the user's charge rate 
record. 


BLINDACCTNG 


BLINDACCTNG - BIT(1). The BLIND ACCounTiING field is a flag which, if set, 
specifies that this user is only to see resources used, and not charge rates 
or actual monetary units. 


BUDLIM 


BUDLIM - SBIN. The BUDget LIMit field contains the amount of charges which 
this job or session is allowed to incur. This field is recorded in hundredths 
of pennies. 


CALCNT 


CALCNT - SBIN. The CALCNT field contains the total number of monitor services 
(PMMEs) executed during this job or session. 


CCARS 


CCARS - SBIN HALF. The Control Command Actual Record Size field contains the 
size of the last run unit invocation command. 


CCBUF 


CCBUF - CHAR(256). The Control Command BUFfer contains the text of the first 
record of the last run unit invocation. 


CCDISP 


CCDISP - SBIN HALF. The Control Command DISPlacement field contains the 
position within the last run unit invocation at which the beginning of options 
may be found. 


CPFLAGS1 


CPFLAGS1 - BIT(36). CPFLAGS1 is used by the monitor to communicate with the 
command processor and is also available for use by the command processor as a 
word where he may remember user directives. 


Bits 0 -> 8 are used by the monitor to communicate job step information to the 
command processor. These bits are not to be set or reset by the command 
processor. The meanings of these bit settings are: 


CP_LOGOFF# When set indicates that the system has 
*400000000000'0 detected a Line hang-up of a time-sharing 
terminal or an operator abort of a user 
and indicates to the command processor that 
no more job steps are allowed. This bit may 
be set in conjunction with any of the other 
CPFLAGS1 bits that are owned by the monitor. 


CP_JSTEP# Indicates that the user is at Job Step. 
"200000000000 '0 
CP RUND# Indicates that all levels of exit control 


*100000000000'o processing are completed and the user is 
about to be rundown. 


CP_YC# Indicates that the command processor jis 
‘040000000000 '0 being entered because the time-sharing 
user has typed the Control-Y sequence. 


z=» 
1 
NN 


CP_YCPMME# 
‘020000000000 '0 


CP_STTART# 
"010000000000 'o 


The following bits are also used for monitor / command processor or 


Indicates that the command processor is 
being entered because of an M$YC monitor 
service request. 


Used only by the monitor. Indicates that 
a Start Step Accounting record has been 
written. This bit is reset when the Stop 
Step Accounting record is written. 


command processor communication: 


CP_STARSACCH 
"000020000000 'o 


Set by LOGON if the '*S ACCOUNTING’ option 
of SUPER: was specified for this user. When 
this bit is set, :ACCTLG records will be 
written to the user's *S file as well. 


CP_LASTCPEXISTS# Set by LOGON if the "LAST CPROC' option 


'9000010000000'0 


CP_LASTCP# 
*000004000000'o 


CP_FIRSTCP# 
‘000002000000 '0O 


CP_STARPROC#H 
'000001000000'0 
CP_DRIBBLE# 
"000000100000 'o 


CP_EXIT# 
*000000020000'0O 


CP_KEEPDS# 
'000000010000'0 


CP_PROCACCT# 
*000000001000'Oo 


CP_STEPACCT# 
*000000000400'O 
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of SUPER has been specified for this user. 
Indicates that the default Command Processor is 
to make its final MS$CPEXIT to this user's Logoff 
command processor and not use the delete user 
form of MSCPEXIT. 


To be set by the command processor when issuing 
an MS$CPEXIT to the logoff command processor. 
This allows one final job step after the monitor 
has set CP_LOGOFF#. 


LOGON sets this bit when exiting to the user's 
command processor. 


Set by the monitor whenever a proprietary 
accounting record is written to the *§ file. Refer 
to MS$ACCT in the Monitor Services Reference Manual. 


To be set and reset by the command processor 
to indicate to the monitor if interactive 
terminal transactions are to be recorded on 
the file or device assigned to the M$DRIBBLE 
DCB. 


Set by the monitor to indicate that the error 

in JIT. USRERR is not to be reported to the user. 
The command processor should, however, use the 
value of JIT.USRERR.SEV as the severity level 

of the error message Last reported to the user. 


This bit may be set by the command processor 
to indicate that the monitor is not to release 
the command processor dynamic data segments. 


Set by the monitor whenever a run unit from the 
:SYS account that has been LINKed with the 
PROCACC option is put into execution. When this 
bit is set, the monitor will cause proprietary 
start and stop records to be written to the *S 
file. 


Set by LOGON if the ‘STEPACCNT' option of 
SUPER was specified for this user. When set, 
the monitor will cause job step start and stop 
records to be written to the *S file. 


JIT Fields 


LOGON / 


The remainder of the bits in CPFLAGS1 may be used as seen fit by the command 
processor. IBEX has predefined the bits for a specific use as follows: 


CP SOMENOTIFY# There is something to NOTIFY user. 


*000040000000'0 

CP_SKIPABORT# Don't abort user at this time 
*000000040000'0 

CP_TRMNATE# Logoff this user after rundown 
*000000004000'0 

CP_NOTIFY# NOTIFY user of changes in BATCH jobs 
*000000002000'0 

CP_STEPLMT# Step Limits in effect 
*000000000200'0 

CP_PROTECT# Don't prompt !quit 
*000000000100'O 

CP_BUFFULL# Command in BSJIT.CCBUF 
*000000000040'0 

CP_CFREAD# Read from XEQ file 
‘000000000020'0 

CP_ECHO# Echo commands from XEQ 
*000000000010'0 

CP_BRK# Break received 
*900000000004'0 

CP_SCREECH# Prevent multiple snaps when IBEX aborts 
*000000000002'0 

CP DELTA# 'U command found 


'000000000001'o 


CTIME 


CTIME - SBIN. The Compensatory TIME field contains the number of microseconds 
by which this quantum will be shortened due to I/0 operations. This value is 
the number of physical I/0 operations done this quantum times the 1/0 Time 
Allowance CIOTA) for the user's mode. 


CURPNUM 


CURPNUM - SBIN HALF. The CURPNUM field is incremented every time a run unit 
that is the target of an MSLINK or MS$LDTRC request jis put into execution. 
This field is decremented when that run unit exits. CURPNUM and HIGHPNUM are 
used when processor accounting is in effect. 


CURRCORE 


CURRCORE - UBIN HALF. The CURRent CORE field contains the current number of 
memory pages chargeable to this user. This value is the result of the 
following calculation of values from the JIT. CURRCORE = PCD + PCDD + PCDS + 
PCDDS + PCADS + PCL + PCV + PCROS - 1. PCP is also added unless 

MMFLGS.FREE PPGS is set. 
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CURSUDO 


CURSUDO - ARRAY(O:7) UBIN BYTE. The CURrent pSeUDO field contains the current 
number of each pseudo resource defined which jis currently allocated to this 
job or session. The order is as defined by TIGR. 


CURTMPDP 


CURTMPDP ~- SBIN. The CURrent TeMP Disk Pack field contains the current number 
of granules of temporary disk space allocated. 


DCBS 


DCB$ - PTR. Contains a pointer to the DCB that was specified on the current 
monitor service request. If the service request doesn't have a DCB associated 
with it, this value will be nil. As with JIT.DCBNO, JIT.DCB$ should not be 
referenced by the user program. 


DCBNO 


DCBNO - UBIN(9). Contains the number of the DCB that was specified on the 
current monitor service request. If the service request doesn't have a DCB 
associated with it, this value will be zero. If an ALTRETURN is made to the 
user request, this field will be placed in the ALTRET frame along with the 
value from JIT.ERR. As with JIT.ERR, JIT.DCBNO should not be referenced by 
the user program. 


DOLL 

DDLL - UBIN HALF. The Dynamic Data Lower Limit field contains the virtual 
page number of the first page in the Instruction Segment that may be used for 
dynamic data. 

DDUL 

DDUL - UBIN HALF. The Dynamic Data Upper Limit field contains the virtual 


page number of the last page in the Instruction Segment that may be used for 
dynamic data. 


DEFEXP 

DEFEXP ~- SBIN HALF. The DEFault EXPire field contains the default value for 
the duration that a file created by this user will be unexpired. This value is 
used if no expiration date is specified when a file is created. 

DEFPRI 

DEFPRI - UBIN BYTE. The DEFault PRIority field contains the default batch 
priority to assign to jobs batched by this job or session. 

DLL 

DLL ~ UBIN HALF. This field contains the Data Lower Limit, which is the 


virtual page number of the first data page of the run unit or standard shared 
processor currently executing. 
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d0$ 


DO$S$ - PTR. The DOS field contains a pointer to an active do-list entry used 
during several file management operations. 


DUL 


DUL - UBIN HALF. This field contains the Data Upper Limit, which is the 
virtual page number of the last data page of the run unit or standard shared 
processor currently executing. If the user is at job step, JIT.DUL will be 
set to JIT.DLL -1. 


ENQS 


ENQ@S - UBIN(18). The ENQS field contains the current number of ENQue 
resources owned by this job or session. 


ERR. 


ERR. The ERR field in the JIT always contains the "current" error code 
reported on this user. This field will be moved to the ALTRET or Stack Frame 
on the Task Control Block of the domain (user, alternate shared Library, 
debugger or command processor) in control at the time of the error. If this 
is the error to be reported to the user following all levels of exit control 
processing, this field will be moved to JIT.USRERR. In any event JIT.ERR is 
subject to change on any change of domain and should therefore never be 


referenced by the user program. JIT.ERR jis in VLP_ERRCODE format and contains 
the following subfields: 


ERR.CODE 


ERR.CODE = DEC(0-16383). This field contains the number that identifies a 
particular error condition. The file B_ERRORS C contains a list of the error 
codes reported by the monitor. 


ERR.FCG 
ERR.FCG = BIT(12). This field contains the two special six bit characters 


that identify the functional code group that is reporting the error. Each 
character is composed of the low-order 6 bits of the ASCII code. 


ERR.MID 


ERR.MID = BIT(6). This field contains the special six bit character that 
identifies which module in the functional code group is reporting the error. 
This character is composed of the low-order 6 bits of the ASCII code. 


ERR.MON 


ERR.MON = BIT(1). This bit is set if this error is reported by the monitor; 
reset if reported by a processor. 


ERR.SEV 


ERR.SEV = DEC(O-7). This field serves a double purpose. Within the monitor 
it is used to indicate the seriousness of an error. When passed by the user 
to MSERRMSG it indicates the level of detail requested in the error message. 
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EUP 

EUP - UBIN HALF. The End User Page field contains the highest virtual page 
number in the instruction segment which is available for user allocation. 
EXTUS 

EXTUS - UBIN. The EXecution Time microseconds field contains the number of 
microseconds (0-9999) of execution time which were not able to be reflected in 
TPEXT or TUEXT at the end of the previous quantum. 

FACCN 

FACCN ~ CHAR(8). The File ‘ACCouNt field contains the users default file 
account. This field is used as the account for any file reference made when 
an account is not explicitly specified. This field may be freely be changed by 
the user, and is not used to determine accessability of files. See MS$SETFMA, 
'DIRECTORY. 

FACNACS 

FACNACS - BIT(18). The File ACcouNt ACceSs field contains the account 
permissions for this user vis-a-vis his current file account (FACCN). 

FACNCM 

FACNCM ~ UBIN(9). The File ACcouNt Character Match field contains the number 
of characters of FACCN which matched on a wild compare. 

FBUC 

FBUC - UBIN HALF. The File Buffer Use Count field contains the total number 
of file buffers (CFPOOLs) currently in use by this user. 

FBUL 

FBUL - UBIN HALF. The File Buffer Upper Limit field contains the maximum 
number of file buffers which file management will use on this user's behalf. 
See !LIMIT FPOOL=n. 

FEXT 

FEXT - ARRAY(O:35) BIT(1). The File EXTension field contains bits which 
specify whether (€'1°B) or not automatic file extension is currently active on 
the four command Line DCBs as well as a number of DCBs of the form M$xx, where 
xx is any of a set of CP-6 special names. 


FPSN 


FPSN - CHAR(6). The File PackSet Name field contains the packset name which 
is to be used in conjunction with FACCN for default file references. 
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FRS 


FRS - BIT(9). The Final Run Status field contains the accumulated abort 
flags. This is a Logical OR of all the flags that may appear in bits 0 
through 4 of RNST as the job step is rundown through all the various levels of 
exit control. Refer to RNST for the EQUated values and the meanings of the 
bit settings in this field. 


For example, if a user is aborted by the operator, RS_XKEY will appear in RNST 
until it is put in either the user's exit control frame or USRRNST. At that 
point the RS_XKEY flag is moved to FRS and RNST is set to zero. Should the 
user exceed MRT in the exit control routine, RS_LIMX would temporarily appear 
in RNST, and both RS_XKEY and RS_LIMX would be set in FRS. 


GAC 


GAC - ARRAY(O:2) UBIN. The Granule ACcounting field contains accounting 
information for files deleted during this job or session which had been 
created by this user. Each entry contains a floating point number which is the 
integral of granules times time. The three entries are for the three charging 
classes of file granules: 


AZSGACBACKUP 0 Granules of files 
eligible for backup. 
AZSGACNOBACKUP 1 Granules of files 
not eligible for backup. 
AZSGACSTOWACT 2 Granules of stowed 


active files. 


HIGHPNUM 
HIGHPNUM ~ SBIN HALF. The HIGHPNUM field is incremented every time a run unit 
that is the target of an MSLINK or MS$LDTRC is put into execution and is reset 


only on job step termination; thus, this is a count of the number of "fetches" 
per job step. 


HPSN 
HPSN - CHAR(6). The Home Pack Set Name field contains the name of the home 


pack set for this user. The principal use of this field is to determine the 
pack set on which to create the user's account if it does not already exist. 


IDELTAT 
IDELTAT - SBIN. The IDELTAT field contains the total quantum time allocated 


at the last quantum end. This will normally be the quantum specified by the 
System manager for this mode, partition, user, etc. 


INSTWORD 


INSTWORD - ARRAY(0:33) UBIN(18). The INSTallation WORD field is a set of four 
values available for installation use. See MSUSRFIELD. 


INTER 


INTER - SBIN HALF. The INTERactions field contains the number of terminal 
interactions which have occurred during this time sharing session. 
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INTTIME 


INTTIME - SBIN. The INTeraction COMPute time field contains the time in 
microseconds expended until the time of the Last terminal read. This is used 
in the calculation of compute time used per interaction. This field is used 
for time sharing only. See also STATS HISTOGRAM. 


JOBNAME 


JOBNAME ~- CHAR(31). The JOB NAME field contains the job name as specified by 
'JOB NAME=x. Regardless of mode, this job name will be carried with any 
output symbiont files generated. It may be subsequently used by a user in 
interrogating the status of output. It will also be displayed on operator 
displays. 


JOBUNIT 
JOBUNIT - ARRAY(0:3) UBIN(18). The JOB UNIT field is a set of four counters 


which are maintained through an entire job and may be used for ‘transaction 
charging’. See MS$CHGUNIT and RATES processor. 


JPEAK 

JPEAK - UBIN HALF. The Job PEAK field contains the maximum value of CURRCORE 
attained during the job or session. 

JRESPEAK 

JRESPEAK - UBIN HALF. The Job RESource PEAK field contains the value which 
must be specified on a !RESOURCE or !ORES command to assure the job of 
successful execution. This value may differ from JPEAK due to overlay path 
considerations. 

JSLEV 

JSLEV - UBIN(3). The Job Statistics LEVel field specifies the type of 


accounting summary which is to be displayed at the end of job or session. See 
'OFF. The field can contain the following values: 


AZ_ALL# 1 Full Accounting Display 

AZ_SUMMARY# 2 One Line Accounting Summary 

AZ_NONE# 3 No Accounting Display 
JTMPDPPK 


JTMPDPPK - SBIN. The Job TeMP Disk Pack Peak field contains the maximum 
amount of temporary disk storage allocated during this job or session. 
JUNK 


JUNK - BIT(18). Bits in JIT.JUNK are used by job step processing and help us 
keep track of what we are doing: 


JJ_MLINKIP# Set while processing an M$LINK or M$LDTRC. 
*000001'O Reset when run-unit has been fetched or the 
LINK/LDTRC process is aborted. 


JJ ULNKRETIP# Set while the MSLINKing program is being restored. 
*000002'0 
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JJ_RTNXIT# 
*000100'0 


JJ_SAVING# 
'010000'0 


JJ_GETTING# 
'020000'0 


JJ_NOSAVE# 
*040000'0 


JJ_SCONA 
'T00000'0 


JJ_SCCSET# 
'900040'0 


JJ_LOGOFF# 
'900200'0 


JJ_BYPASSD# 
'000400'0 


JJ_EVENT# 
*400000'0 


JJ_UDELTA# 
"200000'0 


JJ_BAKIC# 
'001000'0 


JJ_RUNXCON# 
*002000'0 


JJ_DLIB# 
"004000 '0 
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Set while an M$LINKed to run-unit is in execution. 


Set while a program is being saved for MS$SAVE or 
the SAVE command via IBEX. 


Set while a SAVEd image is being restored. 


Set when an M$SCON service request has been issued 
with SAVEFLG = NO specified. When set, all requests 
to SAVE the program are ignored. Once set, this 

bit may only be reset when the job step terminates. 


Set when an MS$SCON service request has been issued 
with XCON ='YES specified. When set, the user's 
exit control routine Cif any) is entered prior to 
writing the save image. Reset only on job step 
termination. 


Set when an MSEXIT, MSERR or MS$XXX service request 
with the STEPCC option is specified (from any domain). 
Reset when the trickle down for exit control reaches 
the user level, thus allowing the user to reset his 
STEPCC settings via his final exit from exit control 
processing. 


Set on MSCPEXIT when CP_LASTCP# is set in CPFLAGS1 
and the user is at job step. Used to allow entry to 
a Logoff Command Processor, and to prevent multiple 
entries to same. 


Set on MS$DRITN when the Debugger indicates that the 
user exit control routine is to be entered. Reset 
when entering the user exit control routine. 


Set on MSDRTN with EVENT = YES specified. Causes 
the Scheduler to defer events for this user until 
after the user program has been re-entered. Reset 
by the scheduler. 


Set when a run-unit is started under control of a 
debugger and not set when a debugger is associated 
via M$ALIB. Control goes to the debugger on all 
user exceptional conditions (break, traps, etc.) 
when this bit is set. 


Set by various monitor service processing routines 

to indicate that control is to be returned to the 
user with the IC is Safe-Store reset to the address 
of the outstanding service request. Used to back out 
of reads when a break is received, for example. 


Set by the exit control logic when the user exit 
control processing is complete and giving exit 
control logic for the special shared processors 
is to be entered. Causes the subcode in the exit 
control frame for the special shared processor to 
be set to one. 


Set when a debugger or ASL is disassociated because 
of an M$DLIB request. Causes the exit control logic 
to be entered (run-up) for the processor being 
disassociated and indicates that the user program is 
to be resumed following exit from the processor's 
exit control routine. 


JIT Fields 


JJ_EXONLY# Set when an execute-only run-unit is put into 
*000010'0 execution. Causes association of a debugger to 
be disallowed. 


JUNK2 


JUNK2 - BIT(18). JUNK2 is the overflow of JIT.JUNK. Bits in this word are 
used as follows: 


JJ2_PACCESS# Set prior to transfer of control to the debugger if 
the user page table has been modified to allow the 
debugger to modify user procedure. Will not be set 
if ALIB. Reset on MSDRTN when write access to 
procedure is reset. 


JJ2 DBRK# Set on MSDRTN when the DBRK = YES option is specified. 
~ Write access to data pages with the SCDRRK bit set in 
the user's page table will be disabled. This bit will 
be reset and the write access allowed on those pages 
when the debugger is next entered. 


JJ2 DFRBRK# Set by the scheduler to defer break control to the user 
= when the break is received during MSYC PMME processing. 
This bit is reset when the command processor issues the 
MSCPEXIT, at which time control will be given to the 
user's break control routine. 


LANG 


LANG - CHAR(1). The LANGuage field is a single character which specifies the 
native Language of the user. This field is used to select the correct error 
message and help files for this user. 


LBJID 


LBJID - UBIN HALF. The Last Batch Job ID field contains the sysid of the last 
batch job submitted by this job or session. 


LLL 


LLL - UBIN HALF. The Library Lower Limit field contains the virtual page 
number of the first page of procedure of an associated run-time Library. 


LNKCNT 


LNKCNT - UBIN(9). Contains the current number of nested M$LINK service 
requests. This field is incremented on every MS$LINK request and decremented 
each time the Linking program is restored. 


LOCK 


LOCK - ARRAY(O:71) BIT(1). The LOCK is really a “KEY". This double word 
contains bit settings that allow users to access restricted processors. The 
LOCK is initialized from the :USERS record when the user enters the system. 
Refer to the description of the KEY option of SUPER in the System Support 
Reference Manual and to the description of the SLOCK and WLOCK options of LINK 
in the Programmer Reference Manual. 
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LOGONTIME 


LOGONTIME - UBIN. The LOGON TIME field contains the time, in UTS units, when 
this job or session was initiated. 


LUL 


LUL - UBIN HALF. The Library Upper Limit field contains the virtual page 
number of the last page of procedure of an associated run-time Library. 


MAXCORE 


MAXCORE - UBIN HALF. The MAXimum CORE field contains the maximum value which 
CURRCORE will be allowed to reach. The word CORE is retained for nostalgia. 
See !RESOURCE, !ORES, !LIMIT. 


MAXEXP 


MAXEXP - SBIN HALF. The MAXimum EXPiration field contains the maximum 
expiration time that this user may specify. 


MAXPRI 


MAXPRI - UBIN BYTE. The MAXimum PRIority field contains the maximum batch 
priority which this job or session may assign to a submitted batch job. 


MAXTMPDP 


MAXTMPDP ~- SBIN. The MAXimum TeMP Disk Pack field contains the maximum number 
of granules of temporary disk space which this job or session is allowed to 
use. 


MMFLGS. 


MMFLGS. The Memory Management FLaGS field contains a set of flags which 
describe the current state of this user from a memory management standpoint. 


MMFLGS.FREE PPGS 


MMFLGS.FREE PPGS - BIT(1). The FREE Procedure PaGeS field indicates whether 
or not the procedure pages in the currently executing run unit are to be 


charged to this user. A value of '1'B specifies that the pages are not to be 
charged. 


MODE 


MODE - UBIN(4). Specifies the type of user. One of the following EQUed 
values will be contained in this field: 


M_BATCH# 1 Batch User 

M_GHOST# 2 Ghost User 

M_INT# 3 Interactive User 

M_TP# 4 Transaction Processing User 


MOUNTS 


MOUNTS - ARRAY(O:2) SBIN HALF. The MOUNTS field contains the number of 


operator mounts required for various resource devices. The entries are used as 
follows: disk=0, tape=1, other=2. 
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MRT 


MRT - SBIN. The Maximum Run Time field contains the maximum allowed execution 
plus service time at the beginning of a job and when a !LIMIT command is 
processed. At any other time it contains the amount of time remaining within 
the Limit. This field is maintained in UTS units. 


MSGID. 


MSGID. The MeSsaGe IDentification field contains the message id of the Last 
comgroup read done by this job or session. This is used primarily for 
Transaction Processing. 


MSGID.PRIMARY 


MSGID.PRIMARY - UBIN. The PRIMARY subfield contains the primary 
identification of the transaction. This value is the same for all spawned 
transactions and identifies the parent transaction. 


MSGID.XT 


MSGID.XT - UBIN. The eXTension field provides a unique identifier for spawned 
transactions. 


NEXTCC 


NEXTCC - UBIN(9). The NEXT Control Command field specifies where the next 
command will be obtained. The possible values are: 


CC_FROMNO# 0 There are no more 

Cend of batch job). 
CC_FROMJOB# 1 Batch job not in XEQ file. 
CC_FROMXEQ# 2 Execute file. 
CC_FROMUC# 3 Time sharing terminal. 


OLTA 


OLTA — ARRAYCO:1) BIT(1). The On Line TApe field contains permission bits 
which allow time sharing users to use 0-2 tape drives without reserving them 
via !ORES. 


OUTPRIO 


OUTPRIO - UBIN(9). The OUTput PRIOrity field contains the priority value to 
be assigned to output symbiont files generated by this job or session. 


PCADS 


PCADS - UBIN HALF. The Page Count ASL Data Segments field contains the total 
number of pages which an ASL has allocated on behalf of this user. 


PCC 


PCC - UBIN HALF. The Page Count of Context field contains the number of pages 
the monitor has allocated for this user's context. User context includes 


HJIT, Page Table, Tstack, JIT, and the first page of the Read Only 


Segment (ROS). 


PCD 


PCD - UBIN HALF. The Page Count of Data field contains the number of pages 
that have been allocated for program data in the instruction segment. 


PCDD 


PCDD ~- UBIN HALF. The Page Count Dynamic Data field contains the number of 
pages which have been allocated dynamically in the Instruction Segment. See 
MSGDP, MSGVP. 


PCDDS 


PCDDS - UBIN HALF. The Page Count Debugger Data Segments field contains the 
total number of pages which a debugger has allocated on behalf of this user. 


PCDS 


PCOS - UBIN HALF. The Page Count Dynamic Segments field contains the number 
of pages that the user has allocated in dynamic data segments. See M$GDS. 


PCL 


PCL - UBIN HALF. The Page Count of Library field contains zero if no run-time 
library is associated, or if a shared run-time Library is associated. If the 
run-LlLibrary becomes unshared, because of an M$DLIB or UNSHARELIB command to 
DELTA, this field will contain the number of pages that have been obtained for 
the run-time library procedure. 


PCP 


PCP - UBIN HALF. The Page Count of Procedure field contains the number of 
pages that have been allocated for procedure. If a shared processor is in 
execution, this number will not be included in the PPC field. 


PCROS 
PCROS ~ UBIN HALF. The Page Count Read Only Segment is the total number of 


pages in the Read Only Segment. This segment contains the TCB and DCBs. The 
first page of this segment is also counted in PCC. 


PCV 


PCV - UBIN HALF. The Page Count Virtual field contains the total number of 
real pages allocated in the three virtual segments, as well as the page tables 
and context necessary to support them. 


PLL 


PLL - UBIN HALF. This field contains the Procedure Lower Limit, which is the 
virtual page number of the first procedure page of the run unit or standard 
shared processor currently executing. 


PMEMTIM 


PMEMTIM - SBIN. The Processor MEMory TIMe field contains the integral of 
CTPEXT + TPSVT) * CURRCORE over all quanta of the entire job or session. This 
is maintained in UTS * page units. 
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PMME_COUNT 


PMME COUNT - SBIN. The PMME_ COUNT and PMME_DATA field are used in conjunction 
to gather data on PMMEs executed when the MOUSE (Monitor Usage Evaluator) 
feature of STATS is in use. The PMME COUNT field contains the current nesting 
Level of a PMME, e.g. an MSERRMSG PMME must invoke an MSOPEN PMME to open the 
appropriate error message file. 


PMME_DATA 

PMME_ DATA - ARRAY(O:2). The PMME DATA field contains various information 
about. starting a PMME for this user. When the PMME completes, the resultant 
information is recorded in the system MOUSE tables. This field is indexed by 
PMME COUNT. 

PMME DATA.CPU 

PMME_DATA.CPU - UBIN. The CPU field contains the service time used by this 
job or session up to the start of this PMME. 

PMME_DATA.I_0 

PMME_ DATA.I_ 0 - UBIN. The I_0 field contains the sum of the three ACCESS 
fields at the start of this PMME. 

PMME_DATA.MISC1 

PMME DATA.MISC1 - SBIN. The MISCellaneous1 and MISC2 fields contain various 
information about the PMME in progress, e.g. for file management operations, 
the ASN field of the DCB. 


PMME DATA.MISC2 


PMME DATA.MISC2 - SBIN. See MISC1. 


PNR 


PNR - UBIN(C9). The Partition NumbeR field contains, if batch, the batch 
partition in which this user is running. 


PPC 


PPC - UBIN HALF. The Physical Page Count field contains the number of real 
memory pages which are only recorded in the page table of this user. The 
value in this field may or may not be equal to CURRCORE depending on a variety 
of factors, such as shared procedure, shared data segments, free procedure, 
etc. 


PPRIV 


PPRIV - BIT(36). Contains bit settings indicating which privileged processors 
may be put into execution by this user. Refer to the description of the 
PPRIVILEGE option of SUPER in the System Support Reference Manual for a 
description of the various processor privileges that may be set. Each of the 
processor privileges have an EQU defined here in the JIT that may be used to 
test the bit setting in JIT.PPRIV. These are of the form: 


XEQU PPR _pprivname# = value; 
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where pprivname is the same as that of the option. 


PRDPRM 
PRDPRM - SBIN. The PeRmanent Disk Pack ReMaining field contains the number of 


granules of permanent space which this job or session is still allowed to 
allocate. Note that this is not the same as file account limits. 


PRFLAGS. 


PRFLAGS. The PRocessor FLAGS field contains a set of flags which are set by 
the command processor based on the run unit invocation Line and other 
commands. 


PRFLAGS.COMMENT 


PRFLAGS.COMMENT - BIT(1). The COMMENT field is a flag which is set unless a 
!DONT COMMENT command was entered immediately prior to this job step. 


PRFLAGS.CONTINUED 
PRFLAGS.CONTINUED - BIT(1). The CONTINUED field is a flag which is set if a 


run unit invocation command is continued. The continuation records may be 
found in the file *CONTINUATION COMMANDS. 


PRFLAGS.LIST 


PRFLAGS.LIST - BIT(1). The LIST field is a flag which is set unless a !DONT 
LIST command was entered immediately prior to this job step. 


PRFLAGS.LS 


PRFLAGS.LS - BIT(1). The List Source field is a flag which is set if a fid 
was specified in the fid4& position of the run unit invocation. 


PRFLAGS.NSSYNTAX 
PRFLAGS.NSSYNTAX - BIT(1). The Non-Standard SYNTAX field is a flag which is 
set if a run unit invocation command did not conform to the standard syntax. 


This command will be executed only if the run unit specifies that non-standard 
syntax is allowed. 


PRFLAGS.OU 


PRFLAGS.OU - BIT(1). The Object Unit field is a flag which is set if a fid 
was specified in the fid3 position of the run unit invocation. 


PRFLAGS.OUTPUT 


PRFLAGS.OUTPUT - BIT(1). Field not currently used. 
PRFLAGS.SI 


PRFLAGS.SI ~- BIT(1). The Source Input field is a flag which is set if a fid 
was specified in the fid1 position of the run unit invocation. 
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PRFLAGS.UI 


PRFLAGS.UI - BIT(1). The Update Input field is a flag which is set if a fid 
was specified in the fid2 position of the run unit invocation. 


PRIINC 


PRIINC - REDEF PNR UBIN(9). The PRIority INCrement field contains the 
execution priority increment to be given to this system ghost over that 
established for ghosts as a default. 


PRIV. 


PRIV. There are five words that are defined in the JIT that are used to 
verify a user's privilege prior to performing certain system functions for 
this user. A description of the contents of each of these words follows. 
Within each of the words, the bit settings will correspond to a value for 
which an EQU statement is included in BSJIT_C. These are of the form: 


XEQU PR_privname# = value; 
where privname is the same as that of the sub-option available on the 
PRIVILEGE option of SUPER. Please refer to the System Support Reference 
Manual for the names and meaning of these sub-options. 
PRIV.ACTIVE 
PRIV.ACTIVE - BIT(36). Contains the privileges that are currently in effect. 
These active privileges are the combination of PRIV.JOB and PRIV.PRC. These 
privilege bits may also be set and reset by the MSSPRIV and MSRPRIV monitor 
service request. Refer to the Monitor Services Reference Manual for a 
description of these requests. 
PRIV.AUTH 
PRIV.AUTH - BIT(36). Contains the user's privilege indicators as defined, via 
SUPER, in the :sUSERS file. 
PRIV.JOB 
PRIV.JOB - BIT(36). Contains the privileges that have been requested via the 
!PRIV command of IBEX. The privilege must appear in JIT.AUTH before IBEX will 
set it in JIT.JOB. 
PRIV.PRC 
PRIV.PRC - BIT(36). Contains the processor privilege bits, as defined by LINK 
options, from the :SYS processor's head record. If the currently executing 
run unit is not from :SYS, PRIV.PRC is set to zero. 
PRIV.SAVED 
PRIV.SAVED - BIT(36). Contains the value from PRIV.ACTIVE while the 


associated Command Processor is in control. This value is then restored to 
PRIV.ACTIVE when the command processor returns control to the user. 
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PROG ENTRY 


PROG_ENTRY - BIT(9). Set to indicate how the currently executing run-unit was 
put into execution as follows: 


PE _CP# ‘000'0 Started via MS$CPEXIT; 

PE_LINK# '020'0 Started via MSLINK. 

PE LDTRC# '010'O Started via MSLDTRC. 
PSEUDOPES 


PSEUDOPGS - UBIN HALF. The PSEUDO PaGeS field contains the total number of 
pages which the user is charged for but which are not reflected in PPC. 


PSLEV 
PSLEV - UBIN(3). The Processor Statistics LEVel field specifies the type of 
accounting summary which is to be displayed when proprietary processor 


charging is in effect. See JSLEV for possible values. Also see RATES, 
CONTROL. 


PUL 
PUL - UBIN HALF. This field contains the Procedure Upper Limit, which is the 
virtual page number of the last procedure page of the run unit or standard 


shared processor currently executing. If the user is at job step, JIT.PUL 
will be set to JIT.PLL -1. 


REMCPO 


REMCPO - SBIN. This field contains the number of punched cards allowed 
remaining for this job. 


REMDO 


REMDO - SBIN. This field contains the number of pages of DO output remaining 
for this job. 


REMLO 


REMLO - SBIN. This field contains the number of pages of LO output remaining 
for this job. 


RERUN 


RERUN - BIT(1). The RERUN field specifies, if set, that this batch job is 
being rerun as a result of some precipitate termination on a previous run. 


RESCORE 
RESCORE - UBIN WORD. The RESource CORE field contains the current amount of 


resource memory allocated (not necessarily physically allocated). The MAXCORE 
field is always less than or equal to RESCORE. See ! RESOURCE, ! ORES. 


RESPEAK 


RESPEAK - REDEF JRESPEAK UBIN HALF. See JRESPEAK. 
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RNST 


RNST - BIT(9). The RNST field in the JIT always contains the “current" run 
status reported on this user. This field will be moved to the exit control 
frame on the Task Control Block of the domain Cuser, alternate shared Library, 
debugger or command processor) in control at the time of the exit condition. 
If this is the status to be reported to the user following all Levels of exit 
control processing, this field will be moved to JIT.USRRNST. JIT.RNST is 
subject to change on any change of domain and should therefore never be 
referenced by the user program. 


This field contains one of the following EQUed values: 


RS_EXIT# ‘000'O MSEXIT was issued. 


RS_ERR# "001'0O MSERR was issued. 
RS_XXX# ‘002'0 MS$XXX was issued. 
RS_SSP# '004'0 Aborted by Special Shared Processor. 


RS_ABRT# '010'0 Job step aborted by the monitor. This 
may be because of program trap and no 
trap control or an errored monitor service 
request and no ALTRET. 


RS_EKEY# *020'0 Aborted because of operator !€ keyin 
or because on user Control-Y QUIT. 


RS_CAN# '021'0 Batch job has been canceled. 
RS_OFF# '040'0 Logoff by the monitor. 


RS_LIMX# *100'0 Abort because some Limit has been exceeded. 
See description of BSJIT.XLIMFLG. 


RS_DROP# *200'0 Interactive user's Line has disconnected. 
RS_XKEY# *400'0 Abort because of !X keyin by the operator. 
Note that this field may have more than one bit set on to indicate multiple 
exit conditions. 
RUNFLAGS 
RUNFLAGS - BIT(9). Indicates the currently executing process as follows: 
RUN _MON# *001'0 Monitor or Command Processor 
RUN PROC# *002'0 Processor in :SYS Linked with PROCACC 


RUN_USER# "004'0 User program or processor not Linked 
with the PROCACC option 


SCHTIME 


SCHTIME - SBIN. The SCHedule TIME field contains the sum of XTIME, STIME, and 
CTIME as they existed the Last time this user was scheduled for execution. 


SPEAK 


SPEAK - UBIN HALF. The Step PEAK field contains the maximum value of CURRCORE 
attained during the current job step. 
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SRESPEAK 


SRESPEAK - UBIN HALF. The Step RESource PEAK field is the same as JRESPEAK 
for a job step. 


SSLEV 
SSLEV - UBIN(3). The Step Statistics LEVel field specifies the type of 


accounting summary which jis to be displayed at each job step. See JSLEV for 
possible values. Also see !REPORT. 


STAR 


STAR - ARRAY(0O:7). The STAR field contains information about several commonly 
used star files. The entries are in the order: *T,*G,*L,*A,*S,*N,*X,*1. 


STAR.DA 


STAR.DA - UBIN. The Disk Address field contains the disk address of the file 
information field for each of the abovementioned star files. 


STDLOPGS 


STDLOPGS - SBIN WORD. The STanDard LO PaGeS field contains the number of 
printed pages of output which have been generated using the form STDLP. 


STEPCC 


STEPCC - UBIN(9). Contains the Step Condition Code. This field is set from 
the SEV field of the error code at the time of the exit condition from the 
user program: 


CC_EXIT# 0 MSEXIT 

CC_ERR# 4 Job step has been errored. 

CC_XXX# 6 Job step has been aborted. 
STEPS 


STEPS - SBIN HALF. Contains the number of job steps that have been executed 
since this user logged on. 


STEPUNIT 
STEPUNIT - ARRAY(O:3) UBIN(18). The STEP UNIT field is a set of four counters 
which are maintained through a job step and reset to zero at the beginning of 


each job step. These may be used for ‘transaction charging’. See MSCHGUNIT 
and RATES processor. 


STIME 


STIME - SBIN. The Service TIME field contains the number of microseconds of 
service time used this quantum. 


STMPDPPK 


STMPDPPK - SBIN. The Step TeMP Disk Pack Peak field contains the maximum 
amount of temporary disk storage allocated during this job step. 
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SVLOTF 


SVLDTF - BIT(9). The SVLDT field contains bit settings to keep track of 
various functions Cexit control processing and association of DELTA) in the 
course of M$LINK, MSLDTRC, SAVE and GET processing: 


SVL_DIC# "200'0 DELTA was in control at the time of the SAVE. 

SVL_EXIT# '100'0O MSEXIT from exit control for SAVE - Saved 
program is now to be run down. 

SVL_TRTN# '040'0 MSTRIN from exit control for SAVE - Saved 
program is to continue execution. 

SVL LINK# '020'0 MSLINK in progress. 

SVL_LDTRC# '010'O MSLDTRC in progress. 

SVL_MSAVE# '004'0 MSSAVE in progress. 

SVL_YCSAVE# '002'O Control-Y SAVE in progress. 

SVL_GET# '001'0 GET in progress. 


SVTUS 

SVTUS - UBIN. The SerVice Time microseconds field contains the number of 
microseconds (0-9999) of service time which were not able to be reflected in 
TPSVT or TUSVT at the end of the previous quantum. 

SWITCH 

SWITCH - ARRAY(0:35) BIT(1). The SWITCH field contains a set of 36 pseudo 
sense switches which may be set/reset by !SWITCH and set/reset by 
MSSSWITCH/MSRSWITCH. 

SYSID 

SYSID - UBIN HALF. Specifies the unique System Identification number that has 
been assigned to this user by the system. This number is reset only on a cold 


boot or wrap around. ALt operator communication and external or printed form 
of user identification will use SYSID. 


TOP 


TOP ~ UBIN HALF. The Top Dynamic Page field contains the virtual page numnber 
of the highest dynamic page currently allocated. 


TMPGAC. 


TMPGAC. The TeMPorary Granule ACcounting field contains accounting 
information for temporary files used in this job or session. 


TMPGAC.N 
TMPGAC.N - UBIN. The TMPGAC.N field contains the integral of temporary 


granules times time up to the time recorded in TMPGAC.TIME in floating point. 
This is updated each time a temporary granule is allocated or deallocated. 


TMPGAC.TIME 


TMPGAC.TIME - UBIN. The TMPGAC.TIME field contains the time in UTS units of 
the last update of TMPGAC.N. 
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TPEXT 


TPEXT - SBIN. The Total Processor EXecution Time field contains the processor 
execution time used in this job or session prior to the current quantum. This 
is maintained in UTS units. 


TPSVT 


TPSVT - SBIN. The Total Processor SerVice Time field contains the processor 
service time used in this job or session prior to the current quantum. This is 
maintained in UTS units. 


TSLINE. 


TSLINE. The Time Sharing LINE field contains several attributes of a time 
sharing users terminal connection. 


TSLINE.FEX 


TSLINE.FEX - UBIN(C9). The Front End index field contains the FEP number of 
the FEP to which this user's terminal is connected. 


TSLINE.PORT 


TSLINE.PORT - UBIN(18). The PORT field identifies the port or MLCP address on 
the FEP to which this user's terminal is connected. 


TSLINE.SPEED 


TSLINE.SPEED - UBIN(9). The SPEED field contains a number signifying the Line 
speed of this user's terminal. The current values are: 


SPEED baud SPEED baud SPEED baud 
0 50 1 75 2 110 
3 134 4 150 5 200 
6 300 7 600 8 1050 
9 1200 10 1800 11 2000 

12 2400 13 4800 14 9600 

15 19200 © 


Values 0, 1, 3, 8, 10, 11 are not currently supported. 


TUEXT 


TUEXT - SBIN. The Total User EXecution Time field contains the user execution 
time used in this job or session prior to the current quantum. This is 
maintained in UTS units. 


TUSVT 


TUSVT - SBIN. The Total User SerVice Time field contains the user service 
time used in this job or session prior to the current quantum. This is 
maintained in UTS units. 


UMEMTIM 


UMEMTIM - SBIN. The User MEMory TIMe field contains the integral of (TUEXT + 
TUSVT) * CURRCORE OVER all quanta of the entire job or session. This is 
maintained in UTS * page units. 
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UNAME 


UNAME - CHAR(12). The User NAME field contains the user's log on name. 


USER 


USER - UBIN(9). Specifies the User Number that has been assigned to this user 
by the system. This number is used internally as an index into the system 
user tables (BSUSER) and is not used for any external user identification. 


USERWORD 

USERWORD - ARRAY(0:3) UBIN(18). The USER WORD field is a set of four values 
available for user use. See MSUSRFIELD. 

USRDCB 

USRDCB - UBIN(9). Contains the value from DCBNO at the time of the exit 
condition from the user program. Thus, if there is a DCB# associated with the 
error code in JIT.USRERR it will be here. 

USRERR. 

USRERR. Contains the error code that reflects the exit condition of the user 
program. JIT .USRERR is in VLP_ERRCODE format; refer to ERR for an explanation 
of the FCG, MID, MON, CODE and SEV subfields. USRERR only reflects the exit 
condition of the user domain. 

USRIC 

USRIC - UBIN(18). Contains the Instruction Counter at the time of the exit 
condition from the user program. 

USRRNST 

USRRNST - BIT(9). Contains the run status to reflect the exit condition of 
the user program. Refer to RNST for an explanation of the bit settings in 
this field. Note that USRRNST only applies to the exit condition of the user 
domain. For example, if the job step is terminated because a special shared 
processor aborts, RS_ABRT# would have been set JIT.RNST for that special 
shared processor's error processing, but JIT .USRRNST would have RS_ABORT# 
reset and RS_SSP# would be set instead. 

UTIMER 

UTIMER - UBIN. The User TIMER field contains the time, in microseconds, 
remaining before expiration of the timer which the user established with 
MSSTIMER. A value of zero means there is no timer currently established. 
VIRTUAL. 

VIRTUAL. The VIRTUAL field is a structure defining currently open virtual 
data segment files. 


VIRTUAL.DCB# 


VIRTUAL. DCB# - ARRAY(O:2) UBIN(9). The DCBH field contains the DCB number of 
the DCB open to the file which defines each of the virtual data segments. 
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woo 


WOO - CHAR(8). The Workstation Of Origin field contains the name of the 
workstation from which this batch job originated. If the WSN option is 
specified on a !JOB record, that becomes the WOO for the job. Timesharing, 
ghost, and Transaction Processing jobs get their default WOO from the 
authorization file. Regardless of the source of WOO, it is used as the default 
workstation for all unit record output if WSN is not specified. It can also be 
used for banners. 


XCONF 
XCONF - BIT(9). Bits 6 through 8 of the XCONF field are used by the monitor 
to keep track of the exit control activity as control passes from one domain 
to another: ‘ 
XC_URND *004'0 Set when user Level exit control processing 
is completed, or if the user has no request 


for exit control. 


XC_ASL# '002'0 Set when ASL exit control processing 
is complete. 


XC_QUIT '001'0 Set on a QUIT command to DELTA or IBEX. 
Bits 0 through 7 are used to record the prior RNST for multiple entries to 


exit control within any domain. Refer to RNST for the EQUated values and 
meanings of these bits. 


XLIMFLG 


XLIMFLG - BIT(9). When RS_LIMX# is set in RNST, one of the following bits 
will be set in XLIMFLG to indicate what Limit has been exceeded: 


XL_PO# "400'0O Cards Punched 

XL_MEM# '200'0 Memory -only causes abort if restoring a 
an MSLINK or SAVE program image. 

XL_LO# '100'°0 M$LO pages 

XL_DO# '040'0 M$DO pages 

XL_STACK# '002'0 Safe-store Stack or Argument Stack 

XL_TIME# ‘001'0 Maximum Run Time exceeded 

XTIME 


XTIME - SBIN. The eXecution TIME field contains the number of microseconds of 
execution time used this quantum. 


Ycosz 


YCOSZ - UBIN(18). Contains the bound of the MSYC monitor service request CMD 
parameter. This field has meaning only when the CP_YCPMME# bit is set in 
CPFLAGS1. 
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Structure Format 


Each of the structure drawings in this appendix represents one %MACRO entry 
which defines a structure. Comments and most preprocessor constructs have 
been removed from the descriptions to make them easier to read. There are 
one, two, or three sections in each drawing, depending on the data contained 
in the text of the structure and whether the structure is a %MACRO or DCL. 


The first section of each drawing contains an alphabetized List of all the 
parameters specified in the %MACRO header and their default values. If 
substitution keywords are also present, they are Listed alphabetically under 
the parameter to which they apply, along with their values. Most parameters 
are used in the INIT clause of the DCL; in this case the (first) location in 
the structure in which the parameter value will be found is printed opposite 
the parameter name. The format used is ".octal word-byte-bit". If the 
parameter is not referenced in an INIT clause, the location is replaced by 
"eeee’ «2 Only one value per INIT clause may be cross-referenced in this 
manner; if multiple values are present in the INIT clause, the second and 
succeeding ones will be flagged as "not found" (".....") in the parameter 
Listing. 


The second section contains a List of ZEQUs or %SUBs found embedded in the DCL 
source. The fully-qualified name to which they apply appears as a header Line 
prior to the List of source text. 


The third section is the actual text of the DCL and a drawing of the structure 
it generates. The right half of the page contains the structure as it appears 
in the source file, except that comments and preprocessor expressions have 
been removed. The left half of each Line shows the memory layout generated by 
the code to its right on the same Line. The drawing is one word (36 bits) 
wide and continues for as many words as necessary to describe the entire 
structure. The words are divided into four nine-bit bytes to make them easier 
to read. Lower case letters are used to represent the bits occupied by the 
item being described: 


bbbbb - indicates a BIT item. 


ccccce - indicates a CHAR item. 
eeeee - indicates an EPTR item. 
ppppp - indicates a PTR item. 
SSsss - indicates an SBIN item. 
uuuuu - indicates a UBIN item. 


If the data item either begins or ends on a non-byte boundary, its 
representation in the drawing is changed to a string of "421" sequences, 
indicating the value of the bit within the octal nibble of the byte. This 
assists in decoding fields which are non-byte aligned when only an octal 
representation is available. 


Filler or supplementary storage which will be present in the structure is 
indicated by a sequence of one or more periods ("."). 


If a data item generates six or more words of storage, the "middle" words will 
not be printed to conserve space. This omission is indicated by a line of "z" 
characters replacing the vertical bars ("|") normally used to separate bytes. 


Only one occurrence of an array element is shown, to illustrate its shape. 
Blank spaces and/or "Z" Lines represent the remaining space occupied by the 
array. 


Items which are variable-length are shown as one bit (or byte) wide; the user 
must use the actual values used in the structure to determine the true Length 
of the item at execution time. Similarly, arrays with variable upper bounds 
are shown with only one element. 
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Each word in the drawing is preceded by its octal offset from the beginning of 
the structure. The total length of the structure is indicated below the Last 
Line of the DCL in the form ".octal words-bytes-bits". If the structure 
contains variable-length strings or variable-dimension arrays, it is flagged 
as "variable". 


The following sample structure illustrates many of these points. Numbers in 
parentheses refer to the items indicated by the <bracketed> numbers on the 
example. 


(1) The XMACRO or DCL name is printed at the left margin at the beginning of 
the structure drawing and on each continuation page. 


(2) This is a Listing of the parameters in alphabetic order in a two-column 
format. 


(3) Indicates that the storage for "TYPE" begins at word 3 (octal), byte 0, 
bit 0. 


(4) This is the parameter ("TYPE") and its default value ("0"). 


(5) These are the keywords which may be specified to change the value of the 
parameter (Ce.g., "TYPE=TERMINAL" places "3" in the TYPE field of the 
structure) and the values they represent. 


(6) The periods (".") indicate that this parameter was not found in an INIT 


clause or is part of a list of initial values. In this case, the latter is 
true. 


(7) This is the ZEQU and %SUB section. 


(8) This is the fully-qualified name to which these EQUs apply. Note that 
"FPTN" is a parameter which will be changed when this macro is invoked. 


(9) These are the names which may be used when comparing FPTN.V.TYPE# to a 
value. 


(10) The remainder of the entry is the drawing section. 
(11) The right half of this section contains the DCL text. 


(12) The left half of this section contains the drawing of the storage 
generated by the DCL text. 


(13) The location for this Line is indicated in octal. Since there is nothing 
else in the drawing, this Line of the DCL generates no storage. 


(14) This line of the DCL has generated a 72-bit (two word) bit item, 
represented by the b's. OTher items generate e's, u's, and so forth, 
depending on their type. 


(15) This is an array element. Note that the two bytes following it in word 
-4 are blank, indicating that the array occupies this space. 


(16) Although DIRECTION# is a UBIN value, its storage is represented by the 
two bits "42" since it does not end on a byte boundary. The "42" indicates 
that DIRECTION# occupies the Leftmost two bits of the first octal nibble of 
this byte. 


(17) Since HEADER# generates 20 words of storage, it is shortened to its first 
two words and last two words. The "Z" Line indicates that one or more words 
have been omitted to conserve space. 


(18) Since C# is a variable-length string, only one byte is indicated as its 
Length in the drawing. The user would consult the L# byte to determine the 
true Length of C# at run time. 
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(19) Periods indicate supplementary or filler storage. Three bytes of 
supplementary storage are added to L# since it is (by default) ALIGNED. Up to 
seven bytes of filler storage are added to the structure after the last 
character of C# since it is DALIGNED. 


(20) The total length of the structure is octal .34 words, 0 bytes, and 0 


bits; however, since this structure contains a variable-length item, the user 
must adjust the total length appropriately at run time. 
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SAMPLE 


~4-3-2 ABC='0'B weeee INDENT2=10 
NO=""Q'B" Gy-—————>_...... INDENT3=15 
YES=""4'p" ; .31-0-0 L=0 
.32-0-0 c=" ' eeeee PEMT="BIT(72)" 
weoee DCBENIL G>————»__ .3-0-0 TYPE=0 “) 
.4-3-0 DIRECTION=1 FILE=1 @) 
INOUT=3 ) TAPE=2 
INPUT=1 C5 -———> __ TERMINAL=3 
OUTPUT=2 UNDEF=4 


eceee FPTN=SAMPLE 
-4-0-0 INDENT1=5 


FPTN.V.TYPEM 


XEQU TYPE FILE=1; 


/SEQU TYPE_TAPE=2; @ @® 
XEQU TYPE _TERMINAL=3; 
XEQU TYPE_UNDEF=4; 


012345678 012345678 012345678 012345678 


-0-0-0 USER=NIL 
-2-0-0 ZZZ=NIL 


ZEQUs and %SUBs 


+ een toeoeenee-- 5 ated teorc- cornet OCL 

o| +> | | | | 1 FPTN DALIGNED, 
| bbbbbbbbb| bbbbbbbbb| bbbbbbbbb] bbbbbbbbb | 2 USER_ PFEFMT INITCVECTOR( 
|bbbbbbbbb| bbbbbbbbb| bbbbbbbbb]| bbbbbbbbb | 40 


| | | | | 2 
|eeeeeeeee| eeeceeece| eeeeceecee|eeeeeeeee| 
| uuwuuuuuU4 | | | | 
| bbbbbbbbb | | 
| 


| wuuuuuUuUU] UUUUUUUUU 
| 


| 

|sssssssss| +5) | | 

| | | [42 DIRECTIONS UBIN(2) U 
| | | | ABCH BIT(1) INITCABC), 
| | 


3 
1 3 
| 421421] 3 * BIT(6) UNAL INITC 
Reis beret alae ae ee ca 3 HEADER# CHAR(80) INITC' 

-6 |ccccceccecc|ceccecece|ccccccecc|cceccccce| 

z z z z z +GD 

-27 |ccecceccc|ceccecccc|ccccceccc|cccececcc| 

-30 [ccecececec}]cccccecce|cececcecc|cecceccce| 


V 

3 ZZZA# EPTR INITCENTADDR 
3 TYPE# UBIN BYTE UNAL IN 
3 * BIT(9) INITC'O'B) 
3 OCB# UBIN HALF UNAL IN 
3 IDENT#(O:2) SBIN BYTE UN 


| 
| 
| CINDENT1,INDENT2, INDENTS 
| 
| 


| | | | 3 FNAME, 
-31 |uuuuuuuuul]......,-.]. t-D .[aceeeeeee| 4 L# UBIN BYTE INIT(L) 
-32 |ecccecccc]. 4-18) [a eecccccc[cccccccel 4 CH CHARCFPTN.V.FNAME 
33 alse aditar er ape atace rave ve crea! | Solero avon wie! ease wateresee | 
+ + 


012345678 012345678 012345678 012345678 .34-0-0 total len. (variable 


Figure A-1. Sample Structure 


CE62-00 Structure Format A-28 


JIT Structure 


The Job Information Table is illustrated on the following pages. 
structure is available in BSJIT_C.:LIBRARY. 


CE62-00 JIT Structure 


The JIT 


BSJIT=BSJIT STCLASS="BASED(BSJIT$)" 


ZEQUs and ZXSUBs 


--> BSJIT.MODE <-- 
XEQU M_INTH=3; 
XEQU M_BATCH#=1; 
%EQU M GHOST#H=2; 
ZEQU M_TPH=4; 


~-> BSJIT.PRIV.ACTIVE <-- 

ZEQU PR SPCLMM#='000000000001' '03 
ZAEQU PR_EXMM#='000000000002'0 
ZEQU PR MAXMEM#= "000000000004" 0; 
ZEQU PR_MSYS#='000000000010'0O; 
ZEQU PR_JIT#='000000000040'0; 
ZEQU PR_TND#='000000000100' ha 
ZEQU PR _PM#= *000000000200'o 

ZEQU PR —ExPm#= "0000000004000 
XEQU PR —1o0a#='000000001000'0;" 
XEQU PR _10aw#='000000002000'0; 
XEQU PR _CFEP#H="000000020000' 0; 
%EQU PR _MFEP#='000000040000' 0; 
XEQU PR _SYSLOGH= *000000100000'0; 
XEQU PR _GPP#= *000000400000'0; 
ZEQU PR _ASAVE#='000001000000! 0; 
XEQU PR ~SYSCON#=' 000002000000 '0; 
XEQU PR _D0ISPJ0B#='000010000000' 0; 
XEQU PR_FMEFT#= *400000000000'0; 
xEQU ER ERB LKe* 200000000000" 07 
ZEQU PR_FMSEC#='100000000000'0; 
XEQU PR _FMDIAG#='040000000000' 0; 
ZEQU PR_ ~FMREAD#='020000000000'0; 


--> BSJIT.PPRIV <-- 

XEQU PPR ENT RED A= S0o000 00000" OF 
ZEQU PPR_CNTRLC#=' 200000000000 '0; 
XEQU PPR —EFT#='100000000000'0; 

ZEQU PPR ~_EL#='040000000000'0 

ZEQU PPR —L ABEL #="020000000000' 0; 
%EQU PPR ~PIGDA="010000000000' O; 
XEQU PPR _PIGCH= *004000000000'0 

ZEQU PPR ~SPIDERD#= '902000000000' 0; 
XEQU PPR “SPIDERC#=*"001000000000'0; 
ZEQU PPR _SUPER#='000400000000' 0; 
XEQU PPR ~FEPANLZ#=' 000200000000 '0 
ZEQU PPR —SUPERAUTH#='000100000000° 0; 
XEQU PPR _SUPERWSN#='000040000000' 0; 
XEQU PPR ~SUPERFORM#='000020000000' 0; 
XEQU PPR ~PADMIN#='000010000000" 0; 
%EQU PPR ~SUPERD#="000004000000'0; 
XEQU PPR VOLINIT#="000002000000'0; 


Figure A-2. BS$JITO Structure (cont. next page) 
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%EQU PPR_REPLAYA#='000001000000'0; 
%EQU PPR _RATES#='000000400000'0; 


~-> BSJIT.CPFLAGS1 <-- 

ZEQU CP_DELTA#='000000000001'0; 
%EQU CP_SLEAZE#='000000000001'0; 
ZEQU CP_ _SCREECH#='000000000002'0; 
%EQU CP_BRK#='000000000004'0; 
%EQU CP_ _ECHO#='000000000010'0; 
XEQU CP_ CFREAD#='000000000020'0; 
%EQU CP. _BUFFULL#='000000000040'0O; 
xEQU CP ~PROTECT#='000000000100' 0; 
%EQU CP_ _STEPLMT#='000000000200'0; 
ZEQU CP_ STEPACCT#='000000000400'O 
ZEQU CP ~PROCACCT#='000000001000'0 
ZEQU CP _NOTIFY#='000000002000'0; 
*EQU CP _TRMNATE#='000000004000' 0; 
xEQU CP _KEEPDS#='000000010000' 0; 
ZEQU CP_EXIT#='000000020000'0; 
ZEQU CP_SKIPABORT#='000000040000'0; 
ZEQU CP DRIBBLE#='000000100000'0; 

MEQU CP_ INITIALIZE#='000000200000' 0; 
ZEQU CP _TESTMODE#='000000400000'0; 
ZEQU CP _STARPROC#='000001000000' 0; 
MEQU CP_FIRSTCP#='000002000000'0; 

ZEQU CP _LASTCP#='000004000000 '0; 

ZEQU CP_ LASTCPEXISTS#='000010000000 '0; 
“EQU CP _STARSACC#="000020000000'0O; 
%EQU CP_ _SOMENOTIFY#='000040000000'0; 
ZEQU CP_ SSTART#='010000000000 '0; 

ZEQU CP _YCPMME#='020000000000'0; 

XEQU CP _Yc#="'040000000000' 0; 

REQU CP_ _RUND#='100000000000'0; 

ZEQU CP_ _JSTEP#='200000000000'0; 

xEQU cP_LOGOFF#=' 400000000000" 0; 

ZEQU CP_RESET#='417777777777'0; 

ZEQU CP_ _RSSTART#= "407777777777 '03 


me Re 


--> BSJIT.SSLEV <-- 
XEQU AZ_ALL#=1; 
XEQU AZ_SUMMARY#=2; 
XEQU AZ_NONE#=3; 


“-> BSJIT.NEXTCC <-- 
XEQU CC_FROMNO#=0; 
ZEQU CC_ _FROMJOB#H=1; 
XEQU CC _FROMXEQ#= 2; 
XEQU CC _FROMUC#=3; 
MEQU CC_ _FROMXEQEND#=4; 


--> BSJIT.PROG ENTRY <-- 
XEQU PE_CP#='000'0; 


Losssesponracienesivesnhansp-aeseseomavicaisiteeaousccnnisins 


Figure A-2. B$JITO Structure (cont. next page) 
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XEQU PE_LINK#='020'0; 
XEQU PE_LDTRC#='010'0; 


--> BSJIT.RNST <-- 
XEQU RS_EXITH='000'0; 
XNEQU RS_ERR#='001'0; 
ZEQU RS XXX#="002'0; 
XEQU RS_SSPH='004'0; 
XEQU RS_ABRTH='010'0; 
XEQU RS_EKEY#='020'0; 
XEQU RS OFFA="040'0; 
XMEQU RS_LIMX#='100'0; 
ZEQU RS_DROP#='200'0; 
XEQU RS_XKEY#='400'0; 
XEQU RS_CAN#='021'0; 
XEQU RS _PMME#='774'0; 
ZEQU RS CL23#='740'0; 
XEQU RS_CL3#='640'0; 
XEQU RS_XCON#='760'0; 


--> BSJIT.RUNFLAGS <-- 
XEQU RUN MON#='001'0; 

XEQU RUN PROCH='002'0; 
XEQU RUN USER#='004'0; 


“-> BSJIT.JUNK <-- 

ZEQU JJ MLINKIP#='000001'0O; 
ZEQU JJ _LNKRETIP#='000002'0; 
ZEQU JJ_AMERGE#='000004'0; 
ZEQU JJ _EXONLY #= *000010'0; 
ZEQU JJ TENGBIT#='000020'0; 
ZEQU JJTSCCSET#='000040'0; 
ZEQU JJ _RTNXIT#='000100'0; 
ZEQU JJ _LOGOFF#='000200' 0; 
ZEQU JJ _BYPASSD#='000400" 0; 
ZEQU JJ _BAKIC#='001000' 0; 
ZEQU JJ _RUNXCON#= *002000'0 
xEQU JJ ~DLIB#='004000'0; 
ZEQU JJ TSAVEING#='010000' 0; 
ZEQU JJ _GETTING#='020000' 0; 
XEQU JJ _NOSAVE#='040000! 0; 
ZEQU JJ _SCONH= *100000'0; 
ZEQU JJ _UDELTA#= *200000'0; 
XEQU JJ_EVENT#="400000'0; 


--> BSJIT.XCONF <-- 
ZEQU XC_QUIT#='001'0; 
ZEQU XC ~ASL#='002'0; 
XEQU XC ~URND#='004'0; 
ZEQU XC ~DOMAIN#='007'0; 
XEQU XC ~PRNST#='770! 0; 


Figure A-2. BS$JITO Structure (cont. next page) 
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--> BSJIT.STEPCC <-- 
%EQU CC_EXIT#=0; 
XMEQU CC_ERR#=4; 
XEQU CC_XXX#=6; 


--> BSJIT.XLIMFLG <-- 
XEQU XL_TIME#='001'0; 
%EQU XL_STACK#='002'0; 
XEQU XL_TAPE#='004'0; 
“%EQU XL_TDISCH='010'0; 
XEQU XL_PDISCH='020'0; 
XEQU XL_DO#='040'0; 
XEQU XL_LO#='100'0; 
%EQU XL_MEM#='200'0; 
XEQU XL_PO#='400'0; 


--> BSJIT.SVLDTF <-- 
%EQU SVL_DIC#='200'0; 
XEQU SVL_EXIT#='100'0; 
XEQU SVL_TRIN#='040'0; 
ZEQU SVL_READY#='140'0; 
MEQU SVL_LINK#='020'0; 
XEQU SVL_LDTRCH='010'0; 
XEQU SVL_LYNX#='030'0; 
%EQU SVL_MSAVE#H='004'0; 
%EQU SVL_YCSAVE#='002'0; 
ZEQU SVL_SAVE#='006'0; 
XEQU SVL_ECCBH='016'0; 
XEQU SVL_GET#='001'0; 


--> BSJIT.JUNK2 <-- 
XEQU JJ2_DBRK#='000001'0; 
XMEQU JJ2 PACCESS#='000002'0; 


012345678 012345678 012345678 012345678 
Se sS Sa =S + DCL 
| 1 BSJIT STCLASS DALIGNED, 
| MODE UBIN(4) UNAL, 
| * BIT(5), 
| uuuuuuuUL | | USER UBIN(9) UNAL, 
| wuuuuuUUU| UUUUUUUUU | SYSID UBIN HALF UNAL, 
|cccccccce|ccccccecc|cccccecccc|cecececcc| ACCN CHAR(8), 
|cecccccce|cccccececc|cceceeccc|cececcccc| 
| cecccecce|ccccceccc|cccececccc|cececcccc | UNAME CHAR(12), 
| cecceccce|ccccceccec|ccccceccec}ececceccc| 
|cccecccce|ccccccccc|cccceccecc|ccceccccc| 
| ccececccc|ccccecccc|ccccecccc|ceccccccc | FACCN CHAR(8), 
| cccececcc| cccceccccc|ccececcce|ccceccece] 
| cecccccce|ccccccecc|cecccccce|ccecceccc| WOO CHAR(8), 
| ccccccccc|ccccccecce|cccececccc|cecececcc] 
ERR, 
FCG BIT(12), 


| 
421421421|421 | | 
| MID BIT(6), 


| 421421| 


CODE UBIN(14) UNAL, 
SEV UBIN(C3) UNAL, 


| 
| 
|4 | | MON BIT(1), 
| 
| 


| 

| 

| | 

| | | 21421421]421421 
| | | 

| 


| | | PRIV, 
| bbbbbbbbb| bbbbbbbbb| bbbbbbbbb | bbbbbbbbb | 3 ACTIVE BIT(36), 
| bbbbbbbbb| bbbbbbbbb| bbbbbbbbb | bbbbbbbbb] 3 AUTH BIT(36), 
| bbbbbbbbb| bbbbbbbbb| bbbbbbbbb | bbbbbbbbb ]} 3 JOB BIT(36), 
| bbbbbbbbb| bbbbbbbbb| bbbbbbbbb| bbbbbbbbb| 3 PRC BIT(36), 
| bbbbbbbbb| bbbbbbbbb| bbbbbbbbb | bbbbbbbbb | 3 SAVED BIT(36), 
|bbbbbbbbb| bbbbbbbbb| bbbbbbbbb| bbbbbbbbb | PPRIV BIT(36), 


|ccccecccce|cccecccecc|ceccccccc|ccccccece| FPSN CHAR(6), 


lecceccece] | | 


| 
' t 
| J uuuuuuUUu | | OUTPRIO UBIN(9) UNAL, 
| | | uuuuuuuuu | DCBNO UBIN(9) UNAL, 


Figure A-2. BS$JITO Structure (cont. next page) 
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uuuuuUuUUY | YuUUUUUUUU | UUUUUUUUU] UUUUUUUUU 2 *(0:4) UBIN, 
Z z zZ 

2 PRFLAGS, 

SI BIT(1), 

UI BIT(1), 

OU BIT(1), 

LS BIT(1), 

COMMENT BIT(1), 

LIST BIT(1), 

OUTPUT BIT(1), 

NSSYNTAX BIT(1), 

CONTINUED BIT(1), 

* BIT(27), 

SWITCH(O:35) BITC(1), 

ssssssss|sssssssss| CCARS BIN HALF UNAL, 
|sssssssss|sssssssss| CCDISP SBIN HALF UNAL, 

|ccceccccc|ccecccceccc|ceccccccce|cecccccecc | CCBUF CHAR(256), 

Jcccceccec|cccceccecc|ccecccecce|ceccececc| 

Zz Z Zz 

|cccecceccc|ccccceccc|cecccecec|ceecccccc| 

|ccccccccc|cceccccec|cccccccece|cccececcc| 

| uuuuuUUUU | UUUUUUUUU | | USERWORD(0:3) UBIN(18) UNA 

zZ Zz Z 

| uuuuuuUUY | UuUUUUUUU | 

Zz z Z 

| uuuuuuUUU | UUUUUUUUU | 

Zz Z Zz 

| uwuuuuuUU] UuUUUUUUUU | 


4 


1 


WWW WOW WWW Ww 


| 
Zz 
| 
| 
| 
| 
| 
| 
| 
| 
sail eal ca Wanna 
| 


| 
z 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
14 
Is 
| 


INSTWORD(O0:3) UBIN(18) UNA 
JOBUNIT(O:3) UBIN(18) UNAL 
STEPUNIT(O:3) UBIN(18) UNA 


z z z 

| bbbbbbbbb | bbbbbbbbb | bbbbbbbbb| bbbbbbbbb CPFLAGS1  BIT(36), 
USRERR, 

3 FCG BIT(12), 

3 MID BIT(6), 

3 MON BIT(1), 

3 CODE UBIN(14) UNAL, 
3 SEV UBIN(3) UNAL, 
JORG UBIN(18) UNAL, 
USRRNST BIT(9), 

LANG CHAR(1), 

YcOSZ UBIN(18) UNAL, 
USRIC UBIN(18) UNAL, 
BUDLIM SBIN, 
LOGONTIME UBIN, 

JSLEV UBIN(3) UNAL, 
PSLEV UBIN(3) UNAL, 
SSLEV UBIN(3) UNAL, 
NEXTCC UBIN(9) UNAL, 
BILL CHAR(6), 


421421421|421 
421421| 
14 
| | 214214211421421 
| | | 421 
uuuuuUUuUu | UuUuUUUUU) | | 
|bbbbbbbbb | 
| | |cccececcce 
uuuuuUUUU | UuUUUUUUU | 
| uwuuuuuUUU | UUUUUUUUU | 
|sssssssss|sssssssss|sssssssss|sssssssss| 


OMOROLOLULVLVIVION MUIVIVIPROIVIOIVIVE MUIVIVIVIVIVIVIVIVE RVIVIVIVIVIVIVITITD | 
1421 


ee at Reed a Renal pt Meeeedl 2 Mecend 


z 
| 
Zz 
| 
Z 
| 
Z 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


421 | | | 
421| | | 
| uuuuuUUUY | | 
Jccccccccc|cececccce 
ceccccecc|ceccececc|ceccccccce|ceccecece 
uuuuuUUU | 
| vuuuuUuUUU | 


| 
| 
| 
| 
| 
| 
| 
| 4 
| 
| 
| 
z 
| 
| 


NUNNNNNNMNNNN 


DEFPRI UBIN BYTE UNAL, 
MAXPRI UBIN BYTE UNAL, 
BLINDACCTNG BIT(1), 

* BIT(8), 

USRDCB UBINC9) UNAL, 
LOCK(O:71) BIT(1), 


21421421 
uuuuuUuUUU 
4 


ce Pd cee ee eee eee ee eS ee ED rE eon ame ene 


uuuuUuUUU | 
|cccccecccc|cecccecce|cceccccce| 
|ccccccccec|cccccccec|ccecccece|ccceccccc| 

-160 |cececcece|ccccceccec|ccceccecc|ceccccecc| 
Zz Zz Z z Z 

-164 |cccccecec|ccccccecc|cccccccce|ceccecccc] 


-165 |[ccccceecc|cceccccec|cecececcc| cccecccce] 
166 


* UBIN BYTE CALIGNED, 
JOBNAME CHAR(31), 


NM” NNN NN PM 


Figure A-2. B$JITO Structure (cont. next page) 
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- 166 


| uuuuuuUUU| UUUUUUUUU] UUUUUUUUU | UUUUUUUUU | 


NN ~ 


NNNNNNNNNNNNN NNN 


NUNNNNN NAN PP 


NUNNNNNN NN PP 


NN NNN 


NUNNNNMNN 


™m 


2167 |uuuuuuuuu] vuuuUUUUU] UUUUUUUUU |] UUUUUUUU | 
-170 |bbbbbbbbb | | | | 
-170 | bbbbbbbbb| bbbbbbbbb| bbbbbbbbb|] 
2171) [uvuuuuuuuU| UuUuUUUUUUU| UUYUUUUUU] UUUUUUUUU | 
Z Zz Zz Zz z 
2176 | uuuuuuuuU] UuuUUUUUUU | | | 
-176 | | |] uuuuuuuuU] UUUUUUUUU | 
6177 |uuuuuuuuu] uuuuUUUUU | 
.177 | | | wuuuuuUuUU] UUUUUUUUU | 
-200 |uuuuuuuuu] uuuuUuUUUU | 
-200 | | | uuuuuuUUU] UUUUUUUUU] 
-201 |uuuuuuuuu] uuuuuUUUU | 
-201 | | | uuuuuuUUU] UUUUUUUUY | 
-202 |uuuuuuuuu] uuuuUUUUU | 
-202 | | uuuuuuUUU] UUUUUUUUU | 
-203 | uuuuuuuuu] uuuuuUUUU | 
-203 | | uuuuuuUUU] UUUUUUUUU] 
-204 |uuuuuuuuu] uuuuuuUU§ | 
-204 | | uuuuuuUUU] UUUUUUUUU t 
-205 |uuuuuuuuu | uuuuuuUUu] 
-205 | | wuuuuuUUU] UUUUUUUUU | 
-206 | | | 
206 |4 | | | | 
~-206 | 21421421]/421421421| | 
.206 | | | uuuuuuUUU] UUUUUUUUU | 
-207 | uuuuuuuuu| uuuUuUUUUU | | | 
-207 | | | uuuuuuUUU |] UUUUUUUUU | 
-210 |uuuuuuuuu| uuuUUUUUU] 
-210 | | | uuuuuuUUU] UUUUUUUUU | 
-211 | uuuuuuuuu| uuuuuUUUU] 
-211 | J uuwuuuuUUU] UUUUUUUUU | 
-212 |uuuuuuuuul| uuuuuUUUU ft | 
212 | | | 
2212 |uuuuuuuuu] uuuuuUUUU] | 
-212 | | uuuuuuUUU] UUUUUUUUU | 
2213 | uuuuuuuUU | uuuUUUUUU | 
-213 | | | uuuuuuUUU] UUUUUUUUU | 
2214 |uuuuuuuuu] uuuuuuuuu | 
-214 | | uuuuuuUUU] UuUUUUUUU | 
2215 | uuuuuuuuul vuuuuuUu4 | 
2215 | | uuuuuuUUU] UUUUUUUUU | 
-216 | uuuuuuuuu] uuuuUUUUU | 
-216 | | uuuuuuuuUt UuUUUUUUUU | 
-217 | | | | 
2217 |uuuuuuuuu | | | | 
eer. | | |} uuuuuuuUUt 
~220 |4 | | | 
-221 |sssssssss|sssssssss| | 
221 | |sssssssss|sssssssss| 
222 | | 
~222 |uuuuuuuuu| wuuuuUUUU] UuUUUUUUUU] UUUUUUUUU | 
Zz Z Zz Zz Z 
-232 |ppppppppp! ppppppppp| ppppppppp| ppppppppp| 
-233 |ppppppppp! ppppppppp| ppppppppp| ppppppppp| 
-234 |cecccceccc|cceccecce|ccceccecc|ceccccccc] 
2235 |ccccccecc|cccccccce| | | 
235 | bbbbbbbbb| bbbbbbbbb | 
-236 |sssssssss|sssssssss|sssssssss|sssssssss| 
-237 |sssssssss|sssssssss|sssssssss|sssssssss| 
-240 |sssssssss|sssssssss|sssssssss|sssssssss| 
-241 |sssssssss|sssssssss|sssssssss|sssssssss| 
-242 |sssssssss|sssssssss|sssssssss|sssssssss| 
~243) | uuuuuuUUU | UuUUUUUUUU| UUUUUUUUU] UUUUUUUUU] 
Z Z Zz Z zZ 
~246 | | | | | 
-246 |uuuuuuuuu | vuuuUUUUU] UuUuUUUUUU] UUUUUUUUU| 
Figure A-2. BS$JITO Structure (cont. 
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3 PRIMARY UBIN, 

3 xT UBIN, 

PROG ENTRY BIT(9), 

* BIT(27), 

*(0:4) UBIN, 

PLL UBIN HALF HALIGNED, 
PUL UBIN HALF HALIGNED, 
DLL UBIN HALF HALIGNED, 
DUL UBIN HALF HALIGNED, 
DDLL UBIN HALF HALIGNED, 
DDUL UBIN HALF HALIGNED, 
PCP UBIN HALF HALIGNED, 
PCD UBIN HALF HALIGNED, 
PCDS UBIN HALF HALIGNED, 
PCC UBIN HALF HALIGNED, 
PCROS UBIN HALF HALIGNED, 
PCDD UBIN HALF HALIGNED, 
TDP UBIN HALF HALIGNED, 
EUP UBIN HALF HALIGNED, 
FBUC UBIN HALF HALIGNED, 
FBUL UBIN HALF HALIGNED, 
MMFLGS, 

3 FREE PPGS BIT(1), 

3% BIT(17), 

* UBIN HALF HALIGNED, 
* UBIN HALF HALIGNED, 
PPC UBIN HALF HALIGNED, 


MAXCORE UBIN HALF HALIGNED 
CURRCORE UBIN HALF HALIGNE 
SPEAK UBIN HALF HALIGNED, 
JPEAK UBIN HALF HALIGNED, 
JRESPEAK UBIN HALF HALIGNE 
RESPEAK REDEF JRESPEAK 
UBIN HALF HALIGNED, 
PSEUDOPGS UBIN HALF HALIGN 
SRESPEAK UBIN HALF HALIGNE 


PCDDS UBIN HALF UNAL, 
PCADS UBIN HALF UNAL, 
LLL UBIN HALF UNAL, 
LUL UBIN HALF UNAL, 
PCL UBIN HALF UNAL, 
PCV UBIN HALF HALIGNED, 
* UBIN HALF HALIGNED, 
VIRTUAL, 


3 DCB#(O:2) UBIN(C9) CALIGN 
3 * UBIN(9) CALIGNED, 
FEXT(O:35) BIT(1), 


DEFEXP SBIN HALF UNAL, 
MAXEXP SBIN HALF UNAL, 
STAR(O:7), 

3 DA UBIN, 

DCBS PTR, 

DOS PTR, 

HPSN CHAR(6), 
FACNACS BIT(18), 
STMPDPPK  SBIN, 
JTMPDPPK  SBIN, 
CURTMPDP  SBIN, 
MAXTMPDP  SBIN, 

PRDPRM SBIN, 
GAC(O:2)  UBIN, 
TMPGAC, 

3N UBIN, 


next page) 


CE62-00 


| wuuuuuUUU | UUUUUUUUU| UUUUUUUUU] UUUUUUUUU | 
|} uuuuuuUUU | | 
| bbbbbbbbb | | | 
J uuuuuuUUU | UUUUUUUUU] UUUUUUUUU] UUUUUUUUU| 
Zz Zz Zz Zz Z 
|sssssssss|sssssssss|sssssssss|sssssssss| 
|sssssssss|sssssssss|sssssssss|sssssssss| 
|sssssssss|sssssssss|sssssssss|sssssssss| 
|[sssssssss|sssssssss|sssssssss|sssssssss| 
|sssssssss|sssssssss|sssssssss|sssssssss| 
|sssssssss|sssssssss|sssssssss|sssssssss| 
|sssssssss|sssssssss|sssssssss|sssssssss| 
Isssssssss|sssssssss|sssssssss|sssssssss| 
Isssssssss|sssssssss|sssssssss|sssssssss| 
|sssssssss|sssssssss|sssssssss|sssssssss| 
|Isssssssss|sssssssss|sssssssss|sssssssss| 
Isssssssss|sssssssss|sssssssss|sssssssss| 
|sssssssss|sssssssss|sssssssss|sssssssss| 
Isssssssss|sssssssss|sssssssss|sssssssss| 
|sssssssss|sssssssss|sssssssss|sssssssss| 
|sssssssss|sssssssss| 
lsssssssss|sssssssss| 
|sssssssss|sssssssss| 
|sssssssss|sssssssss| 
| wuuuuuUUU | UUUUUUUUU] UUUUUUUUU |] UUUUUUUUU | 
| uuuuuuUUL | | | | 
| uuuuuUUUU | | | | 
| 14 | | | 
| | 21421421| | | 
| | | wuuuuuUUU| UUUUUUUUU | 
| uuuuuuUUU | UUuUUUUUU] UUUUUUUUU | UUUUUUUUU | 
| wuuuuuUuU | UuUUUUUUU | UUUUUUUUU | UUUUUUUUU | 
| wuuuuuuUy | UuUuUUUUUU |] UuUUUUUUUU] UUUUUUUUU | 
Zz Z Zz Zz 
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bbbbbbbbb | 
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|bbbbbbbbb| bbbbbbbbb| bbbbbbbbb| bbbbbbbbb | 
|sssssssss|sssssssss| | | 
| | |sssssssss|sssssssss| 
| bbbbbbbbb | bbbbbbbbb | | | 
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|sssssssss|sssssssss|sssssssss|sssssssss| 
|sssssssss|sssssssss| 
Isssssssss|sssssssss| 
|sssssssss|sssssssss| 
|sssssssss|sssssssss] 
|sssssssss|sssssssss|sssssssss|sssssssss| 
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| 
| 
| 
| 
| 
| 
| 
| 
| 
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|sssssssss|sssssssss|sssssssss|sssssssss| 
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Figure A-~2. 
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BSJITO Structure (cont. 


3 TIME 
FACNCM 
*(0:2) 
*(0:6) 


CEXT 
STIME 
XTIME 
CTIME 
INTTIME 
SCHTIME 
IDELTAT 
CALCNT 
TPEXT 
TPSVT 
PMEMTIM 
TUEXT 
TUSVT 
UMEMTIM 
MRT 
RCOMT 
RCURT 
RESPT 
TURNT 
UTIMER 
PNR 


UBIN, 
UBIN(9) UNAL, 
BIT(9), 

UBIN, 


SBIN, 
SBIN, 
SBIN, 
SBIN, 
SBIN, 
SBIN, 
SBIN, 
SBIN, 
SBIN, 
SBIN, 
SBIN, 
SBIN, 
SBIN, 
SBIN, 
SBIN, 
SBIN HALF 
SBIN HALF 
SBIN HALF 
SBIN HALF 
UBIN UNAL, 
UBIN(9) UNAL, 


UNAL, 
UNAL, 
UNAL, 
UNAL, 


PRIINC REDEF PNR UBIN(9) U 


RERUN 
* 
LBJID 
EXTUS 
SVTUS 
*(0:6) 


RNST 

FRS 
RUNFLAGS 
LNKCNT 
JUNK 
STEPS 
XCONF 
STEPCC 
XLIMFLG 
SVLDOTF 
YCERR 
CURPNUM 
HIGHPNUM 
JUNK2 

* 

*(0:1) 
REMCPO 
REMLO 
REMDO 
INTER 
STDLOPGS 
ACCESS, 
3 PACKS 
3 TAPES 
3 FORMS 


MOUNTS(O:2) SBIN 
OLTACO:1) 


ARECX 


BIT(1), 

UBIN(8) UNAL, 
UBIN HALF UNAL, 
UBIN, 

UBIN, 

UBIN, 


BIT(9), 

BIT(9), 

BIT(9), 

UBIN(9) UNAL, 
BIT(18), 

SBIN HALF UNAL, 
BIT(9), 

UBIN(9) UNAL, 
BIT(9), 

BIT(9), 


BIT(36) ALIGNED, 


SBIN HALF UNAL, 
SBIN HALF UNAL, 
BIT(18), 

BIT(18), 

SBIN, 
SBIN 
SBIN 
SBIN HALF 
SBIN HALF 
SBIN WORD, 


HALF 
HALF 


UNAL, 
UNAL, 
UNAL, 
UNAL, 


SBIN, 

SBIN, 

SBIN, 

HALF UNAL 
BIT(1), 
UBIN(16) UNAL, 


CURSUDO(0O:7) UBIN BYTE UNA 


RESCORE 
TSLINE, 
3 FEX 


next page) 


UBIN WORD, 


UBIN(9) UNAL, 


| ] uuuuuuUUU| | | 3 SPEED UBIN(9) UNAL, 
| | | uuuuuuUUU] UUUUUUUUU] 3 PORT UBIN(18) UNAL, 
|sssssssss|sssssssss|sssssssss|sssssssss| PMME COUNT SBIN, 

| | PMME_DATACO:2), 

| vuuuuuuUU |] UuUuUUUUUU] UUUUUUUUU] UUUUUUUUL | 3 cePy URTN, 

iy asuuuuuuyu | uuuuuuUUU |] UuUUUUUUUU | UUUUUUUU | s.10 UBIN, 
Isssssssss|sssssssss|sssssssss|sssssssss| 3 MISC1 SBIN, 


|sssssssss|sssssssss|sssssssss|sssssssss] 3 MISC2 SBIN, 

Zz Zz Z Z Z 

| uuuuuUuUUU | UUUUUUUUU | | | ENQ@S UBIN(18) UNAL, 
| | |bbbbbbbbb] bbbbbbbbb | * BIT(18), 

| vuuuuUUUU| UUUUUUUUU| UUUUUUUUU | UUUUUUUUU | *(0:7) UBIN WORD; 


012345678 012345678 012345678 012345678 .366-0-0 total Length 


Figure A-2. BS$JITO Structure 
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eeee. BSJITO=BSJITO eeeee STCLASS=BASED 
012345678 012345678 012345678 012345678 


.0 1 BSJITO STCLASS DALIGNED, 
-O [uuuuuuuuu] vuuuuUUUU] UUUUUUUUU] UUUUUUUUU] 2 *(0:23) UBIN WORD, 
Z Z Zz Zz Zz 
-30 |uuuuuuuuul] uuuuuUUUU| UUUUUUUUU| UUUUUUUUU | 2 *(0:101) UBIN, 
Z Zz Zz Zz. Zz 
| uuuuuUuUUU | UUUUUUUUU |] UUUUUUUUU | UUUUUUUUY| 2 *(0:17) UBIN, 
Z Z Zz Z Zz 


| uuuuuUuUUU | UUUUUUUUU| UUUUUUUUU| UUUUUUUUU | *(0:31) UBIN, 
Zz Z Z Zz Zz 
| uuuuuuUUU | UUUUUUUUU| UUUUUUUUU] UUUUUUUUU | *(0:27) UBIN, 
Z Zz Zz Zz Z 
| uuuuuUUUY | UUUUUUUUU | UUUUUUUUU | UUUUUUUUY | *(0:7) UBIN, 
Zz Z zZ Zz Zz 
| uuuuuUuUUU | UUUUUUUUU | UUUUUUUUU | UUUUUUUUU | *(0:33) UBIN; 


012345678 012345678 012345678 012345678 .366-0-0 total Length 


Figure A-3. BSJITOX Structure 
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Note: Index references indicate the page on which the paragraph containing the 
index term actually ends. Should the paragraph straddle two pages, the actual 
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*A ~- 11-13 11-14 

ACCESS./BSJIT - A-1 

ACCESS.FORMS/BSJIT - A-1 

ACCESS.PACKS/BSJIT - A-1 

ACCESS.TAPES/BSJIT - A-1 

Accessing the JIT - 8-1 

Accessing the Task Control Block (TCB) - 8-3 
ACCN/BSJIT - A-1 

Accounting Considerations - 8-22 

Addressing Data within a Virtual Segment - 8-16 
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Addressing User Memory from Command Processor - 11-15 
Addressing User Memory from Debugger - 11-20 
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Alternate Shared Library - 11-22 
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ANLZ - 11-5 

annotation - 7-15 

APE - 3-12 

ARECX/BSJIT - A-~1 

Argument Segment, addressing from debugger - 11-20 
ASL - 11-22 

ASL Capabilities - 11-27 

ASL Recovery - 11-28 

ASL system file - 11-24 

ASL-User Interface - 15-14 
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CTIME - A-4 
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DDUL - A-5 
DEFEXP - A-5 
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DLL - A-5 
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ERR.CODE - A-6 
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ERR.SEV - A-6 
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MODE - A-12 
MOUNTS - A-12 
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PCADS - A-13 
PCC - A-13 

PCD - A-14 

PCOD - A-14 
PCDDS - A-14 
PCDS - A-14 


PCL - A-14 
PCP - A-14 
PCROS - A-14 
PCV - A-14 
PLL - A-14 


PMEMTIM - A-14 
PMME_COUNT - A-15 

PMME DATA - A-15 
PMME_DATA.CPU - A-15 
PMME_DATA.I 0 ~ A-15 
PMME_DATA.MISC1 - A-15 
PMME_DATA.MISC2 ~ A-15 
PNR = A-15 

PPC - A-15 

PPRIV - A-16 

PRDPRM - A-16 

PRFLAGS. - A-16 
PRFLAGS.COMMENT - A-16 
PRFLAGS.CONTINUED - A-16 
PRFLAGS.LIST - A-16 
PRFLAGS.LS - A-16 
PRFLAGS.NSSYNTAX - A-16 
PRFLAGS.OU - A-16 
PRFLAGS.OUTPUT - A-16 
PRFLAGS.SI - A-16 
PRFLAGS.UI - A-17 
PRIINC - A-17 

PRIV. - A-17 
PRIV.ACTIVE - A-17 
PRIV.AUTH - A-17 
PRIV.JOB - A-17 
PRIV.PRC - A-17 
PRIV.SAVED - A-17 

PROG ENTRY - A-18 
PSEUDOPGS - A-18 

PSLEV - A-18 
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REMCPO - A-18 
REMDO - A-18 
REMLO - A-18 
RERUN - A-18 
RESCORE - A-18 
RESPEAK - A-18 
RNST - A-19 
RUNFLAGS = A-19 
SCHTIME - A-19 
SPEAK - A-19 
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SSLEV - A-20 
STAR - A-20 
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TMPGAC. TIME - A-21 
TPEXT = A-22 
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USER - A-23 
USERWORD - A-23 
USRDCB - A-23 
USRERR. - A-23 
USRIC - A-23 
USRRNST - A-23 
UTIMER - A-23 
VIRTUAL. - A-23 
VIRTUAL.DOCBH - A-23 
WOO - A-24 
XCONF - A-24 
XLIMFLG - A-24 
XTIME - A-24 
YCOSZ - A-24 
BSPIA$S - 11-2 
BANNER - 3-2 
batch queue (AUTO) - 3-4 3-7 
BEAM/MAEB - 3-11 
BILL/BS$JIT - A-1 
BLINDACCTNG/BSJIT - A-2 
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Break Handling - 8-5 

breakpoint - 11-21 

BRN - 7-15 

BUDLIM/BSJIT - A-2 
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Building Shared Libraries - 12-2 

B_USRPTRS D - 11-2 


CALCNT/BSJIT - A-2 

CALENDAR - 3-2 
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CCBUF/BSJIT - A-2 
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CMPR - 3-4 
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Commentary Tools - 5-17 
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Compiler Error Handling - 14-7 

Compiler Options Usages and Conventions - 14-4 
Compiler Output Control Via IBEX - 14-8 
condensed figure - 7-15 


connector - 7-16 
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Control of Faults - 11-11 

Control of XDELTA's Input and Output - 11-10 
Conventions for Language Processors - 14-1 
COPYPGM - 3-13 

CPFLAGS1 - 11-13 

CPFLAGS1/BSJIT - A-4 

CP_LOGOFF#H - 11-13 

Creating a HELP File - 7-25 

Creating Subtopics - 7-22 

Creating Text Source Files - 7-5 

Creating the Error Message File - 6-3 

CRF - 3-10 

CRT terminal - 7-16 

CTIME/BSJIT - A-4 

CURPNUM/BSJIT - A~-4 

CURRCORE/BSJIT - A-4 

CURSUDO/BSJIT - A-5 

CURTMPDP/BSJIT - A-5 
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DCBs for ASL - 11-27 

DCBs for Command Processor - 11-14 
DCBs for Debugger - 11-20 
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Debugger - 11-17 
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DEFPRI/BSJIT - A-5 
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DI - 3-2 
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Displaying Error Messages - 4-11 
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DLL/BSJIT - A-5 
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E Comments - 5-10 

ECC, Debugger Entry - 11-17 
ECHO command (XDELTA) - 11-10 
EDGEMARK - 3-4 3-6 
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Encoding a Source File - 7-19 
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